MX_AGWRAPPER
Reviewed and revised December 2023
xcall MIAMEX, MX_AGWRAPPER, agcmd, parms, response {,timeout)
MX_AGWRAPPER (MIAMEX 177) serves as a convenient wrapper for "raw" ATE commands that are otherwise invoked via a sequence like:
? TAB(-10,agcmd);parms;chr(127);
input "",response
Aside from simplifying the syntax, MX_AGWRAPPER provides some intelligence to deal with the problem of typeahead that may be "in the pipe" at the time the command was issued and thus get mixed into the response.
Parameters
agcmd (Num) [in]
The value of the TAB(-10,x) command to be issued via the wrapper. Normally specified via one of the AG_xxx symbols defined in the ASHINC:ashell.def file (e.g. AG_XFUNCS).
parms (String) [in]
The list of parameters that would normally follow the AG_xxx function, up to but not including the terminating chr(127). Consult the specifications for the AG_xxx function in question.
response (String) [out]
Returns the string response which normally would otherwise end up in the keyboard buffer where it would need to be retrieved via an INPUT statement.
timeout (Num) [in]
Timeout in milliseconds (0 for infinite), after which the operation will give up waiting for the response and will return with a null response. For commands that are normally quick to respond (e.g. AG_DATETIME), the default timeout is 7500 ms. For certain commands which are known to potentially take a long time to complete (e.g. AG_XFUNC, AG_XFUNCS, AG_FTP, etc.) the default timeout is set to 0 (infinite). You can disable the timeout entirely by setting it to -1 (see Comments, below).
Comments
There isn't anything to be gained by using the MX_AGWRAPPER function to issue a command that does not receive a response (e.g. AG_MINTITLE). But if you do, set timeout to -1 to disable the wait for response. Otherwise it will wait for the default timeout (7.5 seconds) to expire.
Note that many AG_xxx functions already have direct MX_xxx equivalents. The general purpose MX_AGWRAPPER function is mainly of interest when there is no MX_xxx version of the AG_xxx function, or where the MX_xxx version works only on the server side when you really want it to work on the client side.
Example
This example illustrates using MX_AGWRAPPER to issue the AG_OPTIONS command (to query the ATE client's option flags). First, the traditional approach:
? tab(-10,AG_OPTIONS);"0";chr(127);
input "",OPT1,OPT2
And here is the MX_AGWRAPPER version:
xcall MIAMEX, MX_AGWRAPPER, AG_OPTIONS, "0", RESPONSE$
X = instr(1,RESPONSE$,",")
OPT1 = RESPONSE$[1,X-1]
OPT2 = RESPONSE$[X+1,-1]
Or:
dimx OPT(0), s, 0, auto_extend
xcall MIAMEX, MX_AGWRAPPER, AG_OPTIONS, MXOP_GET, RESPONSE$
OPT() = RESPONSE$ ! OPT(1)=first value, OPT(2)=second
Note that in this case, the RESPONSE$ variable would be set to a pair of comma-separated numbers (e.g. "123452,34123"), so we need to extract the values out of the string into individual variables, either by manual parsing (as in the first version), or taking advantage of the direct assignment to an array feature (see Whole Array Assignment). Either approach may result in more code than in the traditional version, except when when response contains just a single value. But the main benefit of MX_AGWRAPPER is to eliminate the potential complications of the INPUT operation. For example, if the client fails to respond for some reason, or sends just one value instead of two, the INPUT statement will wait forever (possibly displaying a "?"), while the MX_AGWRAPPER call will gracefully timeout. (In the above example, the timeout would default to 7500 ms. We could have specified a shorter timeout, but since it would only matter in the rare case where the client was not responding as expected, it makes more sense to error on the conservative side in order to allow for some unexpected network delay, than to time out prematurely.)
History
2015 January, A-Shell 6.1.1399: the wrapper routine now handles certain ZTERM legacy commands (AG_FTP, AG_SHLEXEC and AG_WINEXEC) more robustly than before. These commands differ from the standard ATE commands for which MX_AGWRAPPER was designed because they only return a single character, rather than a string with a CR terminator. Previously these worked fine in the case of success, because the successful code of chr(13) matched the response termination character expected by AG_MXWRAPPER. But in the case of failure, the chr(3) response would either abort the program or would be ignored. Now the single character error response (chr(3)) is returned in the MX_AGWRAPPER response parameter, as you would normally expect when using MX_AGWRAPPER.
