8.2.1 What is a Subcommand Handler

A subcommand handler is a piece of code, that is called to handle
a command to an external environment in REXX. It must be either a
subroutine in the application that started the interpreter, or a
subroutine in a dynamic link library. In any case, when the
interpreter needs to execute a command to an external environment,
it will call the subcommand handler, passing the command as a
parameter.
Typically, an application will set up a subcommand handler before
starting a REXX script. That way, it can trap and handle any
command being executed during the course of the script.

Each subcommand handler handles one environment, which is referred
to by a name. It seems to be undefined whether upper and lower
case letters differ in the environment name, so you should assume
they differ. Also, there might be an upper limit for the length of
an environment name, and some letters may be illegal as part of an
environment name.

Regina allows any letter in the environment name, except  ASCII
NUL; and sets no upper limit for the length of an environment
name. However, for compatibility reasons, you should avoid
uncommon letters and keep the length of the name fairly short.

The prototype of a subcommand handler function is:

     APIRET APIENTRY handler(
           PRXSTRING command,
           PUSHORT flags,
           PRXSTRING returnstring
      ) ;

After registration, this function is called whenever the
application is to handle a subcommand for a given environment. The
value of the parameters are:

     [command]
          The command string that is to be executed. This is the
          resulting  string after the command expression has been
          evaluated in the REXX interpreter. It can not be empty,
          although it can be a  zero-length-string.
     [flags]
          Points to an unsigned short which is to receive  the
          status of the completion of the handler. This can be one
          of the following:  RXSUBCOM_OK, RXSUBCOM_ERROR, or
          RXSUBCOM_FAILURE. The contents will be used to determine
          whether  to raise any condition at return of the
          subcommand. Do not confuse  it with the return value.
     [returnstring]
          Points to a RXSTRING which is to receive the return
          value from the subcommand. Passing the return value as a
          string makes it  possible to return non-numeric return
          codes. As a special case, you  might set
          returnstring.strptr to NULL, instead of  specifying a
          return string of the ASCII representation of zero.

Note that it is not possible to return nothing in a subcommand,
since this is interpreted as zero. Nor is it possible to return a
numeric return code as such; you must convert it to ASCII
representation before you return.

The returnstring string will provide a 256 byte array which the
programmer might use if the return data is not longer that that.
If that space is not sufficient, the handler can provide another
area itself.  In that case, the handler should not de-allocate the
default area, and the new area should be allocated in a standard
fashion.


 PREV   NEXT