# AG\_WINEXEC

> [HTML Version](ag_winexec.htm)

_Reviewed and revised December 2023_

**tab(-10, AG\_WINEXEC); cmdlin; \{"~"; workdir;\} chr(127);**     [Tab(-10,x) Syntax Notes](ag_xxx_syntax-notes.md)

AG\_WINEXEC (23) executes a Windows command line on the local Windows workstation or ATE client. Note that unlike most AG\_xxx functions, the delimiter here is a tilde ("~") rather than a comma. If _workdir_ is specified, it must be separated from _cmdlin_ with a tilde.

**Parameters**

_cmdlin_

A string containing a valid Windows command line. The string may contain any of the suffix characters supported by HOSTEX[xs](keyword-types.md) to control how the command line is executed and whether we have to wait for it to complete, as summarized in the following table. Only one suffix option, at max, is allowed, and it must be preceded by a space. See History notes below for macros that can be used in _cmdlin_.

| **Suffix** | **Description** |
|------|------|
|  | (no suffix) The process launched by _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. |




_workdir_

establishes the working directory context for the command; if not specified, the current workstation directory is used.

**Response**

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[xs](keyword-types.md) 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.

u **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](mx_copyfile.md)[xs](keyword-types.md) 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 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[xs](keyword-types.md). 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 miame.ini. Or:

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

The above command would VUE ATE's log file.