8.6.1 The System Exit Handler

Just like the subcommand handler, the system exit handler is a
routine supplied by the application, and is called by the
interpreter when certain situations occur. These situations are
described in detail later. For the examples below, we will use the
output from SAY as an example.

If a system exit handler is enabled for the SAY instruction, it
will be called with a parameter describing the text that is to be
written out. The system exit handler can choose to handle the
situation (e.g. by writing the text itself), or it can ignore it
and let the interpreter perform the output. The return code from
the system exit tells the interpreter whether a system exit
handled the situation or not.

A system exit handler must be a routine defined according to the
prototype:
     LONG APIENTRY my_exit_handler(
           LONG ExitNumber,
           LONG Subfunction,
           PEXIT ParmBlock
     ) ;

In this prototype, the type PEXIT is a pointer to a parameter
block containing all the parameters necessary to handle the
situation. The actual definition of this parameter block will
vary, and is described in detail in the list of each system exit.

The exits are defined in a two-level hierarchy. The ExitNumber
defines the main function for a system exit, while the Subfunction
defines the subfunction within that main function.  e.g. for SAY,
the main function will be RXSIO (the system exit for standard I/O)
and the subfunction will be RXSIOSAY. The RXSIO main function has
other sub-functions for handling trace output, interactive trace
input, and PULL input from standard input.

The value returned from the system exit handler must be one of the
following symbolic values:
     [RXEXIT_HANDLED]
          Signals that the system exit handler took care of the
          situation,  and that the interpreter should not proceed
          to do the default  action. For the  SAY instruction,
          this means that the  interpreter will not print out
          anything.
     [RXEXIT_NOT_HANDLED]
          Signals that the system exit handler did not take care
          of the situation, and the interpreter will proceed to
          perform the default  action. For the SAY instruction,
          this means that it must  print out the argument to SAY.
     [RXEXIT_RAISE_ERROR]
          Signals that the interpreter's default action for this
          situation should not be performed, but instead a SYNTAX
          condition  should be raised. Don't get confused by the
          name, it is not the ERROR condition, but the SYNTAX
          condition is raised, using  the syntax error Failure in
          system service (normally numbered  48).
          
In addition to returning information as the numeric return value,
information may also be returned by setting variables in the
parameter block. For instance, if the system exit is to handle
interactive trace input, that is how it will supply the
interpreter with the input string.

It is a good and disciplined practice to let your exit handlers
start by verifying the ExitNumber and Subfunction codes, and
immediately return RXEXIT_NOT_HANDLED if it does not recognize
both of them. That way, your application will be upwards
compatible with future interpreters which might have more sub-
functions for any given main function.



PREV NEXT