8.6.2.2 RXCMD — The Subcommand Exit Handler
The main function code for this exit handler is given by the
symbolic name RXCMD. It is called whenever the interpreter is
about to call a subcommand, i.e. a command to an external
environment. It has only one subfunction: RXCMDHST.
The ParmBlock parameter for this subfunction has the following
definition:
typedef struct {
typedef struct {
unsigned int rxfcfail:1 ;
unsigned int rxfcerr:1 ;
} rxcmd_flags ;
unsigned char *rxcmd_address ;
unsigned short rxcmd_addressl ;
unsigned char *rxcmd_dll ;
unsigned short rxcmd_dll_len ;
RXSTRING rxcmd_command ;
RXSTRING rxcmd_retc ;
} RXCMDHST_PARM ;
The significance of each variable is:
[rxcmd_flags.rxfcfail]
If this flag is set, the interpreter will raise a
FAILURE condition at the return of the exit handler.
[rxcmd_flags.rxfcerr]
Like the previous, but the ERROR condition is raised
instead.
[rxcmd_address]
Points to a character array containing the name of the
environment to which the command normally would be
sent.
[rxcmd_addressl]
Holds the length of rxcmd_address. Note that the last
character is the letter ell, not the number one.
[rxcmd_dll]
Defines the name for the DLL which is to handle the
command. I'm not sure what this entry is used for. It is
not currently in use for Regina.
[rxcmd_dll_len]
Holds the length of rxcmd_dll. If this length is set to
zero, the subcommand handler for this environment is not
a DLL, but an EXE handler.
[rxcmd_command]
Holds the command string to be executed, including
command name and parameters.
[rxcmd_retc]
Set by the exit handler to the string which is to be
considered the return code from the command. It is
assigned to the special variable RC at return from the
exit handler. The user is responsible for allocating
space for this variable. I have no clear idea what
happens if rxcmd_retc.strptr is set to NULL; it might
set RC to zero, to the null string, or even drop it.
It seems that this exit handler is capable of raising both the
ERROR and the FAILURE conditions simultaneously. I don't know
whether that is legal, or whether only the FAILURE condition is
raised, since the ERROR condition is a sort of subset of
FAILURE.
Note that the return fields of the parameter block are only
relevant if the value RXEXIT_HANDLED was returned. This applies
to the rxcmd_flags and rxcmd_retc fields of the structure.
PREV NEXT