XSUBR

Invoke an external routine with the specified arguments

WSupported on Windows

USupported on Unix

VSupported on OpenVMS

NSupported in Synergy .NET

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.

Only public routines (those not marked INTERNAL) can be used with XSUBR in Synergy .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).

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