TRAPINPUT()
 Allows supervision of CA-Clipper input commands
------------------------------------------------------------------------------
 Syntax

     TRAPINPUT(<cProcedure>,[<lParameter>]) --> cOldProcedure

 Arguments

     <cProcedure>  Designates the name of the procedure that is called
     during active CA-Clipper input commands.

     <lParameter>  Designates whether a parameter is passed internally to
     the specified trap procedure.  If this logical parameter is .T., then no
     parameter is passed internally to the specified trap procedure.  This
     allows you to significantly improve performance.

     ()  If this function is called without a parameter, the previously set
     trap is uninstalled.

 Returns

     This function returns the name of the previously set trap procedure.  If
     no trap was set, TRAPINPUT() returns a null string.

 Description

     This function is different from a CA-Clipper key trap.  When one of the
     CA-Clipper input commands is active, the specified trap procedure is
     always called when CA-Clipper attempts to retrieve the keyboard input.
     This function is completely independent of whether or not there really
     has been a keyboard input.  Additionally, the ensuing inputs are not
     influenced in any way, but are passed to the CA-Clipper command
     unchanged.

     The Procedure Call
     Three parameters are transmitted by the called procedure, as with
     CA-Clipper trap procedures.  These parameters are the procedure name,
     the line number, and the variable name.  All three parameters are
     transmitted unless the <lParameter> option is .T.

     Important!  In contrast to CA-Clipper key traps, these internal
     input commands do not have the option to ignore the interruption because
     no internal input routine is reentrant.  You cannot, under any
     circumstances, use the same input command in the called procedure.  This
     applies the GET/READ, PROMPT, ACCEPT, and any similar input
     instructions.  You can easily use INPUTMODE(.T.) to determine which
     input command is currently active when you call a procedure.

 Notes

     .  In contrast to CA-Clipper SET KEY TO traps, recursions are
        automatically avoided.

     .  If the designated procedure does not exist, then the function
        uninstalls itself and does not produce a runtime error.  If a warning
        regarding a missing procedure is required during linking, use the
        EXTERNAL <procedure> statement.

 Example

     The following example shows a MEMOEDIT() extension to a very simple
     communications program.  This is only intended to demonstrate a possible
     application.  This solution is unsuitable for a full fledged
     communications program because at some point the memory available to
     MEMOEDIT() would be insufficient.

     The main purpose of the example is to show how using TRAPINPUT() can
     convert characters from the serial port into keyboard input for a
     CA-Clipper application.  Each time the CA-Clipper program looks for
     keyboard input, the characters in the serial port input buffer are added
     to the available keyboard buffer.  Please notice that the example uses
     KEYSEND().

     To complete this example, all local keyboard input is transmitted
     through the TRAPANYKEY() procedure over the serial port.  The other
     terminal is expecting an echo of these characters.  Alt-C remains
     functional in this example.  The application can also be changed to take
     into account other control keys.

     CLEAR

     nPort := 1

     COM_OPEN(nPort, 1000)
     CON_DTR(2, .T.)
     COM_INIT(nPort, 1200, "N", 8 , 1)

     TRAPINPUT("Trap1")
     TRAPINPUT("Trap2")


     cTextVar := SPACE(5000)
     cTextVar := MEMOEDIT(cTextVar)

     COM_CLOSE(nPort)

     RETURN

     PROCEDURE Trap1(a, b, c)

        IF COM_COUNT(nPort) > 0
           KEYSEND(CHARMIX(COM_READ(nPort), CHR(0), .T.)
        ENDIF

        RETURN

     PROCEDURE Trap2(nKey)

        IF nKey <= 255
           COM_SEND(nPort, CHR(nKey))
        ELSE
           KEYSEND(I2BIN(nKey), .T.)
        ENDIF

        RETURN