Command Handler Interface

Applications can create custom command handlers that function like operating command shell environments. These named evironments can be invoked with the Rexx ADDRESS instuction and applications can create Rexx instances that direct commands to custom application command handlers by default.

Command handlers are registered with an interpreter instance when it is created. See Interpreter Instance Options for how to register a handler with an interpreter instance.

The command handlers are registered as a function pointer to a handler routine. When a Rexx program issues a command to the named ADDRESS target, the handler is called with the evaluated command string and the name of the address environment. The handler is responsible for executing the command and returning a return code value back to the Rexx program. Handlers are called using the following function signature:

RexxObjectPtr RexxEntry TestCommandHandler(RexxExitContext *context,
     RexxStringObject address, RexxStringObject command)

Arguments

context

A RexxExitContext interface vector for the handler call. The RexxExitContext provides access to runtime services appropriate to a command handler. For example, the exit context can set or get Rexx variables, invoke methods on objects, and raise ERROR or FAILURE conditions.

address

A String object containing the target command environment name.

command

A String object containing the issued command string.

Returns

Any object that should be used as the command return code. This value will be assigned to the variable RC upon return. If NULLOBJECT is returned, a 0 is used as the return code. The return code value is traditionally a numeric value, but any value can be returned, including more complex object return values, if desired.

For normal commands, the command is processed and a return code is given back to the Rexx program. The interpreter recognizes two different abnormal return states for commands, ERROR and FAILURE. An ERROR condition indicates there was some sort of error return state involved with executing a command. These could be command syntax errors, semantic errors, etc. FAILURE conditions are more serious conditions. One traditional FAILURE condition is the unknown command error.

Command handlers raise ERROR and FAILURE conditions using the RaiseCondition() API provided by the RexxExitContext. For example:

// if this was an unknown command, give our generic unknown command return code
if (errorStatus == COMMAND_FAILURE) {
    // Note:  The return code needs to be included with the FAILURE condition
    context->RaiseCondition("FAILURE", command, NULLOBJECT, context->WholeNumber(-1));
    // just return null...the RC value is picked up from the condition.
    return NULLOBJECT;
}
else if (errorStatus == COMMAND_ERROR) {
    // Note:  The return code needs to be included with the ERROR condition
    context->RaiseCondition("ERROR", command, NULLOBJECT, context->WholeNumber(rc));
    // just return null...the RC value is picked up from the condition.
    return NULLOBJECT;
}
// return the RC value for the command, which need not be 0
return context->WholeNumber(rc);