Reviewed November 2011

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

The MIAMEX function MX_AGWRAPPER (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 TAB(-10,agcmd), 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 5000 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).

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 5000 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, make sure to set the timeout to , then make sure to set the timeout to 1 ms, since it without any response, it won't return until the timeout expires.

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

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