This appendix describes how to interface applications to Rexx or extend the Rexx language by using Rexx application programming interfaces (APIs). As used here, the term application refers to programs written in languages other than Rexx. This is usually the C language. Conventions in this appendix are based on the C language. Refer to a C programming reference manual if you need a better understanding of these conventions.
The features described here let an application extend many parts of the Rexx language or extend an application with Rexx. This includes creating handlers for subcommands, external functions, and system exits.
are commands issued from a Rexx program. A Rexx expression is evaluated and the result is passed as a command to the currently addressed subcommand handler. Subcommands are used in Rexx programs running as application macros.
are direct extensions of the Rexx language. An application can create functions that extend the native Rexx function set. Functions can be general-purpose extensions or specific to an application.
are programmer-defined variations of the operating system. The application programmer can tailor the Rexx interpreter behavior by replacing Rexx system requests.
Subcommand, function, and system exit handlers have similar coding, compilation, and packaging characteristics.
In addition, applications can manipulate the variables in Rexx programs (see Variable Pool Interface), and execute Rexx routines directly from memory (see Macrospace Interface).
The basic requirements for subcommand, function, and system exit handlers are:
Rexx handlers must use the APIENTRY (_stdcall) linkage convention. Handler functions should be declared with the appropriate type definition from the Rexx.H include file. Using C++, the functions must be declared as extern C:
RexxSubcomHandler
RexxFunctionHandler
RexxExitHandler
A Rexx handler must be packaged as either of the following:
An exported routine within a dynamic-link library (DLL)
An entry point within an executable (EXE) module
A handler must be registered with Rexx before it can be used. Rexx uses the registration information to locate and call the handler. For example, external function registration of a dynamic-link library external function identifies both the dynamic-link library and routine that contains the external function. Also note:
Dynamic-link library handlers are global to the system; any Rexx program can call them.
Executable file handlers are local to the registering process; only a Rexx program running in the same process as an executable module can call a handler packaged within that executable module.