Updated November 2017; see History
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 Fn'ATE'SBX in SOSLIB:[907,11] 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 OSVERCLI.SBX in SOSLIB:[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 provided in the documentation for HTTP.SBR, subtopic "ATE."
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 subroutine.
History
2017 November, A-Shell 6.5.1621, Corruption avoidance fix: the string containing the argument list was previously used in place, but since the area is within the terminal system output buffer, it was subject to possible corruption by other functions that use the output system. This could have interfered with the operation of XGETARG(S). For example, in the following SBX code, the second XGETARG might have returned incorrect information due to potential sharing of the same buffer space with DEBUG.PRINT:
XGETARG 1,ARG1
DEBUG.PRINT "ARG1 = "+ARG1
XGETARG 2,ARG2
This patch eliminates the danger of such a conflict.
2016 October, A-Shell/ATE 6.3.1534: Eliminate 1K limit on size of returned string.