Please enable JavaScript to view this site.

Rewritten December 2023

Numeric Function:

tab(-10, AG_XFUNC); sbxname; arg1, arg2,....argn; chr(127);     Tab(-10,x) Syntax Notes

String Function:

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

No Response:

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.

Parameters

sbxname

File name (no device or extension) of an SBX Subroutine stored in the SBX search path (normally BAS: ) of the ATE or windows client. For the XFUNC and XFUNCS versions, it  must include a RETURN expression.

arg1, arg2, ..., argn

Zero or more arguments passed to the SBX. These will appear to the target SBX as individual arguments passed in an XCALL statement.

Response

For AG_XFUNC, the response is a single numeric value:

numvalue CR

For AG_XFUNCS, the response is a string, which may potentially be in the form of a list, depending on the SBX, so should be parsed appropriately:

strvalue CR

For AG_XFUNC2, there is no response

 

Example 1

writecd tab(-10,AG_XFUNC);"CALCLCD", 21, 35; chr(127);

input "", lcd

 

This example passes a pair of numbers to a routine CALCLDC.SBX on the client and gets back the least common denominator.  Note that writecd was used in place of the more typical print or ? statement in order to get the benefit of automatic comma delimiters. The equivalent print statement version would be:

? tab(-10,AG_XFUNC);"CALCLCD"; ","; 21; ","; 35; chr(127);

 

or

 

? tab(-10,AG_XFUNC);"CALCLCD,21,35"; chr(127);

 

The target CALCLDC.SBX would be internally invoked on the client side via:

xcall CALCLCD, 21, 35

 

To work properly, it should be constructed something like this:

xgetargs value1,value2           ! receive the two arguments

result = Fn'LCD(value1,value2)   ! calc the least common denominator

return (result)                  ! return the result

 

Example 2

writecd tab(-10,AG_XFUNCS);"FGREP", file$, pattern$; chr(127);

input line "", match$

 

This example passes a filespec and a pattern to a routine FGREP.SBX on the client to search the specified field for the specified pattern, returning the first match, if any. Note the use of input line rather than just input for the response since we can't be sure if the return string contains commas (or anything at all).

Example 3

writecd tab(-10,AG_XFUNC2);"ARCFILE", file$, file2$, file3$; chr(127);

 

This example calls a routine ARCFILE.SBX on the client to archive the specified files, whatever that may mean. There is no response in this case.

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, 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 variations with a return value (i.e. AG_XFUNC and AG_XFUNCS but not AG_XFUNC2), see MX_AGWRAPPER as a way to encapsulate the two parts of the operation (Tab output and response input) into a single operation. In particular, its timeout feature would provide a measure of robustness given that the complexity of these remote calls increases the possibility of unexpected failures which might otherwise leave the application stuck waiting for a response that isn't coming.

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.

Created with Help+Manual 9 and styled with Premium Pack Version 5 © by EC Software