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

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

The function 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.):

Suffix	Description
	(no suffix) The process launched by the cmdlin takes the foreground and A-Shell must wait for it to exit.
&	The process is launched in minimized mode and runs independently of A-Shell (i.e. A-Shell doesn’t wait for it.)
%	The process is launched minimized, but A-Shell still waits for it to complete. This is mainly useful for quick commands where you don’t want to distract the user with its display.
$	The process is launched in the foreground but A-Shell does not wait for it.

 

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,23);"notepad.exe %MIAMEFILE%";chr(127);

xcall ACCEPN,A

! launch calculator and don't wait

? TAB(-10,23);"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 Tab(-10,23) always executes a Windows command line on the local workstation.

Also see Shell Execute (below).

Update Note: Build 969 of 21 Oct 06

Two new macros have been added:

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

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

Although it is possible to execute a Windows file copy using the XCOPY command, these new macro commands are much cleaner in the sense that they don't cause a Command Prompt window to appear, won't prompt you for anything, and don't have such complicated switches. The macro implementation is essentially the same function as MX_COPYFILE and they share the same flags. ($MOVE is equivalent to $COPY with the +1 flag; +2 can be added in either case to allow an existing destination to be overwritten.) If ~flags is omitted, the default is 0 (don't overwrite an existing destination).

Update Note: Build 932 of 31 May 2005

AG_WINEXEC now supports a new macro $DEL to delete a file. For example:

? TAB(-10,23);"$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.

Update Note: Build 926 of 4 April 2005

A special symbol, "$ATE", may now be used with Tab(-10,23) to make it easier to launch another ATE session. For example:

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

? TAB(-10,23);"$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,23);"$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, Tab(-10,23) 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,23);"$ATE telnet ";CFG$;" $";chr(127);

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

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

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

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

The above command would VUE ATE's log file.