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