Update January/July 2015; see History

xcall MIAMEX, MX_AGWRAPPER, agcmd, parms, response {,timeout)

MX_AGWRAPPER 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 command, up to but not including the terminating chr(127). Consult the specifications for the AG_xxx command 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).

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]

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 parse it out, resulting in more code than in the traditional version. (It is of course more convenient when the response is a single string value requiring no additional parsing.) In either case, the main benefit is to eliminate the potentially troublesome 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.)

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 commands 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 command, or where the MX_xxx version works only on the server side when you really want it to work on the client side.

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.

2009 June, A-Shell 5.1.1159:  Routine added to A-Shell