Open topic with navigation
WTSupported in traditional Synergy on Windows
WNSupported in Synergy .NET on Windows
USupported on UNIX
VSupported on OpenVMS
xcall XSUBR(subroutine[, arguments, …])
value = %XSUBR(valfunction[, arguments, ...])
xcall XSUBR(nonvalfunction, return[, arguments, ...])
The return value of the specified external function. (^VAL)
The name of the external routine to invoke or the value returned from %XADDR. (a or n)
The arguments to the specified external routine. (a or n)
The name of the external function to invoke or the value returned from %XADDR. This must be a ^VAL function. (a)
The name of the external function to invoke or the value returned from %XADDR. This cannot be a ^VAL function. (a)
The return value of the specified external function. (a or n)
The XSUBR subroutine invokes the specified external routine with the specified arguments. The first syntax calls a subroutine, the second syntax calls a ^VAL function, and the third syntax calls a non‑^VAL function.
You cannot use XSUBR to access a class method.
If the routine is not present, the runtime generates a “Cannot access external routine routine_name” error ($ERR_RTNNF).
If you use ^VARARGARRAY, note that either subroutine, valfunction, or return is the last declared argument for this routine, depending on which form of XSUBR you are using.
Synergy/DE for OpenVMS uses shared executable images to implement an ELB. Only Synergy DBL routines in the main program can be invoked by XSUBR. If the target routine is not found in the main program image, LIB$FIND_IMAGE_SYMBOL is used to search the shared image list created by calls to OPENELB.
The order of shared image searches is in reverse order of calls to OPENELB: the first image searched will be the one referenced in the most recent call to OPENELB. Also, OPENELB must be called to access routines in a shared image; XSUBR does not have direct access to the shared image linked to the program image by the OpenVMS linker.
We recommend that you avoid using XSUBR in Synergy .NET, as it can impede performance. Unless you have backward links (where XSUBR is the only way to get there without rearranging DLLs), you should always code direct method calls in .NET.
In addition, we strongly recommend against using XSUBR for device development. If there is no compile‑time binding for this routine, it won’t be included in the compiled device application (even if there are runtime bindings).
Only public routines (those not marked INTERNAL) can be used with XSUBR in Synergy .NET.
See Structured exception handling for important information about exception handling with XSUBR.
The example below calls the rname external subroutine.
record rname ,a30 ;External routine name arg1 ,a5 arg2 ,d2 arg3 ,d1 quit_wanted ,d1
proc repeat begin xcall get_mnu(rname, quit_wanted) ;Wait for menu selection
if (quit_wanted .eq. 1)
exitloop xcall xsubr(rname, arg1, arg2, arg3) end xreturn
The following example calls the blue ^VAL function. The return value for blue is returned in the results variable.
arg1 ,d1 ,4 arg2 ,d2 ,74 results ,d2
external function blue ,i
proc open(1, o, "tt:") results = %xsubr('blue', arg1, arg2) writes(1, "r_arg = " + %string(results)) end
function blue, ^VAL a_arg1 ,d a_arg2 ,d record results ,i4
proc results = a_arg1 + a_arg2 freturn results