8.3.1 What is an External Function Handler

An external function handler is a piece of code, that is called to
handle external functions and subroutine calls in REXX. It must be
either a subroutine in the application that started the
interpreter, or a subroutine in a dynamic link library. In any
case, when the interpreter needs to execute a function  registered
as an external function, it will call the external function
handler, passing the function name as a parameter.
All external functions written in a language other than REXX must
be registered with the interpreter before starting a REXX script.

An external function handler can handle one or more functions.
The handler can determine the function actually called by
examiining one of the parameters passed to the handler and act
accordingly.

The prototype of a subcommand handler function is:

     APIRET APIENTRY handler(
           PSZ name,
           ULONG argc,
           PRXSTRING argv,
           PSZ queuename,
           PRXSTRING returnstring
      ) ;

After a function is registered with this function defined as the
handler, this function is called whenever the application calls
the function. The value of the parameters are:

     [name]
          The  function called.
     [argc]
          The number of parameters passed to the function. Argv
          will contain argc RXSTRINGs.
     [queuename]
          The name of the currently define data queue.
     [returnstring]
          Points to a RXSTRING which is to receive the return
          value from the function. Passing the return value as a
          string makes it  possible to return non-numeric return
          codes. As a special case, you  might set
          returnstring.strptr to NULL, instead of  specifying a
          return string of the ASCII representation of zero.

The returnstring string will provide a 256 byte array which the
programmer might use if the return data is not longer that that.
If that space is not sufficient, the handler can provide another
area itself.  In that case, the handler should not de-allocate the
default area, and the new area should be allocated in a standard
fashion.  if the external function does not return a value, it
should set returnstring to an empty RXSTRING.  This will enable
the interpreter to raise error 44; Function did not return data,
if the external function is called as a function.  If the external
function is invoked via a CALL command, the interpreter drops the
special variable RESULT.

The handler returns zero if the function completed successfully.
When the handler returns a non-zero value, the interpreter will
raise error 40; Invalid call to routine.


 PREV   NEXT