$perlcall(<subroutine> [<text>])

The <subroutine> argument is a dword which is different from most function arguments.

These functions call a given subroutine in the embedded perl interpreter and return the subroutines return value.

• <subroutine> is the name of a subroutine in perlspace to call.
• If <text> is given, it forms the first argument to the sub.
• The subroutine is called in scalar context and the scalar value of the return value of the subroutine is returned.

The perlxcall function gives you much more control.

These functions are much faster and less dangerous than the perl function since the perl interpreter does not have to parse and/or compile the input. The downside is that you have to define or load the subroutine with a call to the perl function before they can be used.

$perlxcall() is useful as a prime mover of data between the perl and epic environments, and in situations where one line of code has too many or too few consequences to handle at once. In reality, it is unlikely that you will ever need to make use of all the arguments.

You can't use these functions to call primitive perl functions.

Nothing will be returned if the perl interpreter hasn't been started with a call to the perl function or if an error occurred. Otherwise, the returned scalar (in scalar context), or the number of items added to the specified array (in list context) are returned.

If the perl sub returns an array when it should return a sub, that is, if it ignored wantarray, the number of items in the array will be returned, and the array will be discarded.

Assume the following (somewhat dangerous) perl sub has been defined:

# Execute all arguments as shell commands, returning one output line
# per call in scalar context, or all at once in array context. Since
# a local @return always overshadows a global one in perl, you can
# call this sub in any sequence and it will still work as described.
sub system {
    local @return if wantarray;   # @return is global otherwise.
    for (@_) {push @return,`$_`}  # Execute all arguments.
    return wantarray ? @return : shift @return ;
}

Then, the following will work thusly:

$perlcall(system ls)  Returns the first line of ls output.
                      Repeated calls will add more data to the
                      return list, but won't be returned until the
                      output from the first one is emptied out.
$perlcall(system)     Returns the next line of ls output.  No
                      commands are actually run.
@delarray(in)         You want to be careful..  :-)
$perlxcall(system in out -1 ls)
                      Dumps the output to out all at once.  out
                      is now a running log of the shell commands.
                      Repeated calls will add to this log.  These
                      can be accessed with [[getitem]].  See
                      [[Arrays]]

You could then msg or notice somebody with the output of these functions at a leisurely rate which will not get you flooded off the server.

Of course, you should never ever ever call this particular sub with text received from the network. There are better ways to do these things too, so you probably shouldn't have it defined, however, this does serve as a useful example.