Updated June 2025
XFUNC (sbxname, arg1,...,argn)
XFUNC$ (sbxname, arg1,...,argn)
XFUNC and XFUNC$ execute an external SBX routine, returning a numeric or string value. They are nearly identical to XCALL in that they load and call an SBX, except that they are expressions (which return values) rather than statements (which do not). The only special requirement for the SBX routine is that it return a value— numeric for XFUNC or string for XFUNC$—via a special form of the RETURN statement. The return value will be ignored if the SBX is called via XCALL, allowing a single SBX to work with both XFUNC/XFUNC$ and XCALL.
Parameters
sbxname (String) [in]
name (without path or extension) of the SBX subroutine which implements the function
arg1,...,argn (any data types) [in/out]
arguments passed to the SBX routine
Examples
Here is an example of an SBX to concatenate two strings that can be called via XCALL (returning the result in the 3rd parameter), or via XFUNC$ (returning the result as the value of the function):
map1 var1$,s,30," abra "
map1 result$,s,50
xcall CONCAT2,var1$," cadabra ",result$
? "xcall result: "; result$
? "xfunc$ result: "; xfunc$("CONCAT2", var1$," cadabra ")
end
Both the XCALL and the XFUNC$ statements above invoke the same CONCAT2.SBX routine, which, if written to handle both calling methods, will result in the same output for the two print statements above, i.e.
.RUN TSTCONCAT2
xcall result: abracadabra
xfunc$ result: abracadabra
This sample program illustrates the use of the XPUTARG and RETURN (expr) statements to support both calling interfaces.
program CONCAT2, 1.0(100) ! sbx to strip spaces and concatenate 2 strings
!------------------------------------------------------------------------
!NOTES
! xcall CONCAT, arg1$, arg2$, result$
!or
! xfunc$("CONCAT", arg1$, arg2$) - returns result as value of function
!------------------------------------------------------------------------
++pragma SBX
map1 params
map2 arg1$,s,0
map2 arg2$,s,0
map2 result$,s,0
xgetargs arg1$, arg2$
xcall TRIM, arg1$
xcall TRIM, arg2$
result$ = trim$(arg1$) + trim$(arg2$)
xputarg 3,result$ ! return result in 3rd param (if XCALL)
return (result$) ! in case called via XFUNC$
end
Comments
As with subroutines, any of the arguments passed to XFUNC/XFUNC$ can be updated by the SBX routine, although any such updates will only have an effect if the argument was passed as a variable.
As with other system-defined functions, XFUNC and XFUNC$ are expressions—not labels—and thus cannot be invoked with the CALL statement.
See Also
