XSUBR
Invoke an external routine with the specified arguments
WTSupported in traditional Synergy on Windows
|
WNSupported in Synergy .NET on Windows
|
USupported on UNIX
|
VSupported on OpenVMS
|
xcall XSUBR(subroutine[, arguments, ...])
or
value = %XSUBR(valfunction[, arguments, ...])
or
xcall XSUBR(nonvalfunction, return[, arguments, ...])
Return value
value
The return value of the specified external function. (^VAL)
Arguments
subroutine
The name of the external routine to invoke or the value returned from %XADDR. (a or n)
arguments
The arguments to the specified external routine. (a or n)
valfunction
The name of the external function to invoke or the value returned from %XADDR. This must be a ^VAL function. (a)
nonvalfunction
The name of the external function to invoke or the value returned from %XADDR. This cannot be a ^VAL function. (a)
return
The return value of the specified external function. (a or n)
Discussion
The XSUBR subroutine enables programs to determine at runtime what external routine will be called by invoking the specified external routine with the specified arguments. The first syntax above 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.
See also
%XADDR routine
Examples
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 end
The following example calls the blue ^VAL function. The return value for blue is returned in the results variable.
main record 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 end