Interface for writing external function and subroutine code

This topic describes the system interfaces for writing external functions and subroutines that are load modules. You can write the function or subroutine in assembler or any high-level programming language that can be invoked by using the MVS™ Link Macro and is capable of handling the REXX function interface as documented below (that documentation is in terms of an assembler programming interface). This means that the high-level language must be capable of properly handling the documented register interface, including the handling of parameters passed by using register 1 pointing to an EFPL parameter list, exactly as shown.

Note that for some high-level languages, it may be necessary to write an assembler stub routine which can take the defined REXX function interface (registers, parameters, AMODE, etc.) and manipulate these into a format which can be handled by the specific high-level language routine that is being invoked. For example, for C programs you may need to use an assembler-to-C interface stub to first create a C environment before the stub can pass control to your C-routine. Or, you may need to pass parameters in some different way which your high-level language understands. Refer to language specific documentation for a description of any language specific interface requirements, or for a description of how an assembler stub program can pass control to a routine in the high-level language.

The interface to the code is the same whether the code is called as a function or as a subroutine. The only difference is how the language processor handles the result after your code completes and returns control to the language processor. Before your code gets control, the language processor allocates a control block called the evaluation block (EVALBLOCK). The address of the evaluation block is passed to the function or subroutine code. The function or subroutine code places the result into the evaluation block, which is returned to the language processor. If the code was called as a subroutine, the result in the evaluation block is placed into the REXX special variable RESULT. If the code was called as a function, the result in the evaluation block is used in the interpretation of the REXX instruction that contained the function.

An external function or subroutine receives the address of an environment block in register 0. This environment block address should be passed on any TSO/E REXX programming services invoked from the external function or subroutine. This is particularly important if the environment is reentrant because TSO/E REXX programming services cannot automatically locate a reentrant environment. For more information about reentrant environments, see Using the environment block for reentrant environments.

The following topics describe the contents of the registers when the function or subroutine code gets control and the parameters the code receives.