A-Shell Reference

Reviewed and revised December 2023

"ATE Functions" refer to the operations that can be used with A-Shell's smart client terminal emulator, ATE, as opposed to a traditional dumb terminal. These functions are accessed through a series of tab(-10,x) functions. They apply not only to ATE, but also to A-Shell on all other platforms where ATE is being used as the terminal emulator, or where A-Shell is running on a Windows host machine. Note that many of the functions have higher-level subroutine wrappers, typically using MIAMEX or AUI, which in most cases are preferable, since the wrapper automatically decides whether to execute the command on the server or forward to the client (or provides an option), and also handles the complications of retrieving a response via the keyboard channel. Otherwise, for functions that return a response, the caller has to either use an INPUT statement or the MX_AGWRAPPER function. The main advantage of using the Tab(-10,x) functions directly is that they don’t require A-Shell support on the server side, and thus could be used by nearly any operating system.

The Tab(-10,x) command is equivalent to the raw byte sequence <ESC>GUI<x>.

See the next topic, TAB(-10,x) Function Listing, for a table containing a list of functions, brief descriptions, and links to detailed descriptions.

Usage Notes

The general format of the commands is:

? tab(-10, x); <arg1> <delim> <arg2> <delim>. . .<argn>; chr(127);

where "x" identifies the function. While the function identifier can be a literal number, e.g. 23, it is preferable—and far more legible—to use the corresponding AG_xxx symbol (e.g. AG_WINEXEC) defined in ashell.def. The following two statements, one using the traditional number and the other using the symbol, are equivalent:

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

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

While not strictly mandatory, it is highly recommended that all Tab(-10,x) statements be terminated with a semicolon (as in the examples above). Otherwise, a CRLF will be output (as it is for any PRINT statement which does not end with a semicolon); in the case of Tab(-10,x) commands, that terminating CRLF would be entirely spurious and might cause unwanted side effects on your screen, like scrolling.

The <delim> may vary from one command to the next, but it usually a dash ("-"), tilde ("~"), or comma. Any argument that itself contains an embedded delimiter character must be quoted. It is important to note that in all cases, the literal delimiters must appear in the output string, as the entire string is parsed by the terminal driver (or ATE client) rather than by the compiler. Also note that all Tab(-10,x) commands must be terminated with a chr(127) (which cannot appear in the list of arguments). For example, the AG_SAVERES command takes two arguments and uses a comma for a delimiter. The following would be legal:

? TAB(-10,AG_SAVERES);CMD$;",";ID; chr(127);

? TAB(-10,AG_SAVERES);"S,5";chr(127);

This, however, is not legal syntax:

? TAB(-10,AG_SAVERES);CMD$,ID;chr(127);

The problem with the last example is that the comma separating the two arguments is interpreted by the compiler and runtime system, but not actually output to the terminal device.

If the command returns a response, typically you will need some kind of input statement following the Tab(-10,x) statement to retrieve the response. For example:

? TAB(-10,AG_GETENV); "MIAME"; chr(127);

INPUT LINE "",ENV$

 

INPUT LINE (as shown above) is preferable to INPUT, since the returned text may contain commas (which would act as delimiters). In the case of commands that return a single byte response (typically chr(13) for "ok" and chr(3) for "error", following the ZTERM Escape Sequences protocol), keep in mind that the chr(3) (aka "Control C") will abort your program if you don't take steps to trap it. Typically in these cases, it is better to disable Control-C processing (see CCOFF) and use a byte-oriented input routine like ACCEPN.

The operation of inputting the response can be problematic, due to the possibility of the operator managing to manually force keyboard characters into the input stream ahead of the command input. Typically, the AG_xxx function will lock the keyboard to prevent this, but that can be manually unlocked by the user. And there is also the possibility of type-ahead (characters already typed but not yet received by the application) getting mixed in. In addition, you may not want the returned characters to appear on the screen (for which you can set NOECHO mode, or use an input routine that doesn’t echo, like ACCEPN). To reduce or even eliminate these complications and simplify your application coding, we recommend using the subroutine equivalent of the AG_xxx function (when available, as noted in the table above), and if there is no specific subroutine equivalent, you can use the generic MX_AGWRAPPER function to encapsulate the sending of the command and inputting of the response. The subroutine wrapper generally takes care of all the issues just described.

See Also