8.6.2.4 RXSIO — The Standard I/O Exit Handler

The main code for this exit handler has the symbolic value RXSIO.
There are four sub-functions:
     [RXSIODTR]
          Called whenever the interpreter needs to read a line
          from the user during interactive tracing. Note the
          difference between this subfunction and  RXSIOTRD.
     [RXSIOSAY]
          Called whenever the interpreter tries to write something
          to standard output in a  SAY instruction, even a SAY
          instruction without a parameter.
     [RXSIOTRC]
          Called whenever the interpreter tries to write out
          debugging information, e.g. during tracing, as a trace
          back, or as a syntax error message.
     [RXSIOTRD]
          Called whenever the interpreter need to read from the
          standard input stream during a PULL or PARSE PULL
          instruction.  Note that it will not be called if there
          is sufficient data on the  stack to satisfy the
          operation.

Note that these function are only called for the exact situations
that are listed above. e.g. the RXSIOSAY is not called during a
call to the REXX built-in function LINEOUT() that writes to the
default output stream. TRL says that SAY is identical to calling
LINEOUT() for the standard output stream, but SAA API still
manages to see the difference between stem variables and compound
variables with a ``zero-length-string'' tail. Please bear with
this inconsistency.

Depending on the subfunction, the ParmBlock parameter will have
four only slightly different definitions. It is kind of
frustrating that the ParmBlock takes so many different datatypes,
but it can
be handled easily using unions, see a later section. The
definitions are:

     typedef struct {
           RXSTRING rxsiodtr_retc ;  /* the interactive trace
     input */
     } RXSIODTR_PARM ;
     
     typedef struct {
           RXSTRING rxsio_string ;   /* the SAY line to write out
     */
     } RXSIOSAY_PARM ;
     
     typedef struct {
           RXSTRING rxsio_string ;   /* the debug line to write
     out */
     } RXSIOTRC_PARM ;
     
     typedef struct {
           RXSTRING rxsiotrd_retc ;  /* the line to read in */
     } RXSIOTRD_PARM ;

In all of these, the RXSTRING structure either holds the value to
be written out  (for RXSIOSAY and RXSIOTRC), or the value to be
used instead of reading standard input stream  (for RXSIOTRD and
RXSIODTR). Note that the values set by RXSIOTRD and RXSIODTR are
ignored if the exit handler does not return the value
RXEXIT_HANDLED.

Any end-of-line marker are stripped off the strings in this
context. If the exit handler writes out the string during RXSIOSAY
or RXSIOTRC, it must supply any end-of-line action itself.
Similarly, the interpreter does not expect a end-of-line marker in
the data returned from RXSIODTR and RXSIOTRD.

The space used to store the return data for the RXSIODTR and
RXSIOTRD sub-functions, must be provided by the exit handler
itself, and the space is not de-allocated by the interpreter. The
space can be reused by the application at any later time. The
space allocated to hold the data given by the RXSIOSAY and
RXSIOTRC sub-functions, will be allocated by the interpreter, and
must neither be de-allocated by the exit handler, nor used after
the exit handler has terminated.

 PREV   NEXT