Creating External Functions

The following is a sample external function definition:
Sample external function definition

ULONG SysLoadFuncs(
     PSZ       Name,                   /* name of the function       */
     LONG      Argc,                   /* number of arguments        */
     RXSTRING  Argv[],                 /* list of argument strings   */
     PSZ       Queuename,              /* current queue name         */
     PRXSTRING Retstr)                 /* returned result string     */

Name

Address of ASCIIZ function name used to call the external function.
Argc
The number of elements in the Argv array. Argv will contain Argc RXSTRINGs.
Argv
An array of null-terminated RXSTRINGs for the function arguments.
Queuename
The name of the currently defined REXX external data queue.
Retstr
Address of an RXSTRING for the returned value. Retstr is a character string function or subroutine return value. When a REXX program calls an external function with the REXX CALL instruction, Retstr is assigned to the REXX special variable RESULT. When the REXX program calls an external function with a function call, Retstr is used directly within the REXX expression.

The REXX interpreter provides a default 256-byte RXSTRING in Retstr. A longer RXSTRING can be allocated with DosAllocMem if the returned string is longer than 256 bytes. The REXX interpreter releases Retstr with DosFreeMem when the external function completes.

Returns
An integer return code from the function. When the external function returns 0, the function completed successfully. Retstr contains the function return value. When the external function returns a non-zero return code, the REXX interpreter raises REXX error 40 ("Incorrect call to routine"). The Retstr value is ignored.

If the external function does not have a return value, the function should set Retstr to an empty RXSTRING (NULL strptr). When an external function called as a function does not return a value, the interpreter raises error 44, "Function or message did not return data". When an external function called with the REXX CALL instruction does not return a value, the REXX interpreter drops (unassigns) the special variable RESULT.

---

[Back: Registering External Functions]
[Next: Calling External Functions]