Numeric Function

? tab(-10, AG_XFUNC); sbxname;", arg1, arg2,....argn"; chr(127);

input "",R

String Function

? tab(-10, AG_XFUNCS); sbxname;",arg1, arg2,....argn"; chr(127);

input line "", R$

No Return Value

? tab(-10, AG_XFUNC2); sbxname; ",arg1,arg2,...argn"; chr(127);

AG_XFUNC (25), AG_XFUNCS (75), and AG_FUNC2 (73) invoke a function implemented via an SBX, returning a numeric, string or no result, respectively. In the first two cases, the result is passed back in the keyboard buffer where it can be retrieved via an INPUT or INPUT LINE statement as shown above.

Sbxname must be the name of an SBX—just the name, no device or extension—stored on the DSK0:[7,6] directory relative to the ATE (or local A-Shell/Windows) client.

The arguments to the SBX are passed in the AG_XFUNC/AG_FUNCS statement as a single string with commas between each argument. So for example, the following statement:

? tab(-10,AG_XFUNCS);sbxname$;"arg1,arg2,arg3";chr(127);

gets executed on the client as it it were:

XFUNC$(sbxname$,"arg1","arg2","arg3")

Comments

Getting the SBX installed on the client is outside the scope of the function. To simplify this prerequisite, see the SOSLIB wrapper function Fn'ATE'SBX which automatically takes care of transferring or updating the SBX from the application/server to the ATE/client if necessary, invoking the routine remotely, and return the result.

See the SOSLIB outine OSVERCLI.SBX [907,33] for an example of a function invoked by AG_XFUNCS using the Fn'ATE'SBX$() wrapper.

An example of a standard routine using this mechanism is ATHTTP.SBX.

Note that the SBX may not perform any standard text mode input operations, as these would interfere with the host/client communication (TELNET/SSH) channel. Instead, if input is needed, use AUI functions, e.g. MSGBOX, EVENTWAIT, INFLD (in GUI mode), etc.

Note that AG_XFUNCS is to AG_XFUNC as the underlying built-in function XFUNC$() is to XFUNC(). The former deals with functions returning a string, while the latter deals with functions returning a numeric value. In both cases, if the specified SBX is not found the return value will be -1, although in the case of AG_XFUNCS, it will be a string representing -1, e.g. "-1", as opposed to the numeric value -1. There is no particular limit on the length of the returned string.

For the numeric and string functions, but not for the no-return value function, see MX_AGWRAPPER a way to encapsulate the two parts of the operation (? Tab and input) into a single XCALL.

History

2016 October, A-Shell/ATE 6.3.1534:  Eliminate 1K limit on size of returned string.