Creating Subcommand Handlers

The following example is a sample subcommand handler definition.
Sample definition of a subcommand handler

ULONG command_handler(
  PRXSTRING Command,    /* Command string from REXX            */
  PUSHORT   Flags,      /* Returned Error/Failure flags        */
  PRXSTRING Retstr);    /* Returned RC string                  */

Command

The command string created by REXX.

Command is a null-terminated RXSTRING containing the issued command.

Flags
Subcommand completion status. The subcommand handler can indicate success, error, or failure status. The subcommand handler can set Flags to one of the following values:

RXSUBCOM_OK

The subcommand completed normally. No errors occurred during subcommand processing and the REXX procedure continues when the subcommand handler returns.
RXSUBCOM_ERROR
A subcommand error occurred. RXSUBCOM_ERROR indicates a subcommand error occurred; for example, incorrect command options or syntax.

If the subcommand handler sets Flags to RXSUBCOM_ERROR, the REXX interpreter raises an ERROR condition if SIGNAL ON ERROR or CALL ON ERROR traps have been created. If TRACE ERRORS has been issued, REXX traces the command when the subcommand handler returns.

RXSUBCOM_FAILURE
A subcommand failure occurred. RXSUBCOM_FAILURE indicates that general subcommand processing errors have occurred. For example, unknown commands usually return RXSUBCOM_FAILURE.

If the subcommand handler sets Flags to RXSUBCOM_FAILURE, the REXX interpreter raises a FAILURE condition if SIGNAL ON FAILURE or CALL ON FAILURE traps have been created. If TRACE FAILURES has been issued, REXX traces the command when the subcommand handler returns.

Retstr
Address of an RXSTRING for the return code. Retstr is a character string return code that is assigned to the REXX special variable RC when the subcommand handler returns to REXX. The REXX interpreter provides a default 256-byte RXSTRING in Retstr. A longer RXSTRING may be allocated with DosAllocMem if the return string is longer than the default RXSTRING. If the subcommand handler sets Retstr to an empty RXSTRING (a NULL strptr), REXX assigns the string "0" to RC.

---

[Back: Registering Subcommand Handlers]
[Next: Example]