Product SiteDocumentation Site

18.3. Subcommand Handler Services

For a complete subcommand handler description, see the Open Object Rexx: Programming Guide.

18.3.1. The RXSUBCOM Command

The RXSUBCOM command registers, drops, and queries Rexx subcommand handlers. A Rexx procedure or script file can use RXSUBCOM to register dynamic-link library subcommand handlers. Once the subcommand handler is registered, a Rexx program can send commands to the subcommand handler with the Rexx ADDRESS instruction. For example, Rexx Dialog Manager programs use RXSUBCOM to register the ISPCIR subcommand handler.

Example 18.1. Command RXSUBCOM - REGISTER option

"RXSUBCOM REGISTER ISPCIR ISPCIR ISPCIR"
Address ispcir

See Section 2.1, “ADDRESS” for details of the ADDRESS instruction.

18.3.1.1. RXSUBCOM REGISTER

RXSUBCOM REGISTER registers a dynamic-link library subcommand handler. This command makes a command environment available to Rexx. 

>>-RXSUBCOM--REGISTER--envname--dllname--procname--------------><
Parameters:
envname
The subcommand handler name. The Rexx ADDRESS instruction uses envname to send commands to the subcommand handler.
dllname
The name of the dynamic-link library file containing the subcommand handler routine.
procname
The name of the dynamic-link library procedure within dllname that Rexx calls as a subcommand handler.
Return codes:
0
The command environment has been registered.
10
A duplicate registration has occurred. An envname subcommand handler in a different dynamic-link library has already been registered. Both the new subcommand handler and the existing subcommand handler can be used.
30
The registration has failed. Subcommand handler envname in library dllname is already registered.
1002
RXSUBCOM was unable to obtain the memory necessary to register the subcommand handler.
-1
A parameter is missing or incorrectly specified.

18.3.1.2. RXSUBCOM DROP

RXSUBCOM DROP deregisters a subcommand handler. 

>>-RXSUBCOM--DROP--envname--+---------+------------------------><
                            +-dllname-+
Parameters:
envname
The name of the subcommand handler.
dllname
The name of the dynamic-link file containing the subcommand handler routine.
Return codes:
0
The subcommand handler was successfully deregistered.
30
The subcommand handler does not exist.
40
The environment was registered by a different process as RXSUBCOM_NONDROP.
-1
A parameter is missing or specified incorrectly.

18.3.1.3. RXSUBCOM QUERY

RXSUBCOM QUERY checks the existence of a subcommand handler. The query result is returned. 

>>-RXSUBCOM--QUERY--envname--+---------+-----------------------><
                             +-dllname-+
Parameters:
envname
The name of the subcommand handler.
dllname
The name of the dynamic-link file containing the subcommand handler routine.
Return codes:
0
The subcommand handler is registered.
30
The subcommand handler is not registered.
-1
A parameter is missing or specified incorrectly.

18.3.1.4. RXSUBCOM LOAD

RXSUBCOM LOAD loads a subcommand handler dynamic-link library. 

>>-RXSUBCOM--LOAD--envname--+---------+------------------------><
                            +-dllname-+
Parameters:
envname
The name of the subcommand handler.
libname
The name of the dynamic-link file containing the subcommand handler routine.
Return codes:
0
The dynamic-link library was located and loaded successfully.
50
The dynamic-link library was not located or could not be loaded.
-1
A parameter is missing or incorrectly specified.