COM_KEY()
 Monitors the port using key traps
------------------------------------------------------------------------------
 Syntax

     COM_KEY(<nComPort>,[<nKeyValue1>],[<nKeyValue2>])
        --> lActive

 Arguments

     <nComPort>  Designates the port (1 to 4) where particular activities
     are monitored.

     <nKeyValue1>  Designates the key code placed in the keyboard buffer
     in case an interrupt occurs.  Values permitted with CA-Clipper's SET KEY
     TO command are allowed, as a numeric value or a character.  If this
     parameter is not specified, then the port interrupts are not monitored.

     <nKeyValue2>  Designates another key code that is placed in the
     keyboard buffer when the receiving buffer is 75% or more full.  Values
     permitted with CA-Clipper's SET KEY TO command are allowed, as a numeric
     value or a character.  If this parameter is not specified, the buffer
     overflow is not monitored.

 Returns

     COM_KEY() returns .T. when at least one trap is switched on and returns
     .F. when all monitoring is switched off.

 Description

     COM_KEY() allows you to monitor a port while the program is in a READ.
     In this way, various events at the port can cause a particular key code,
     selected by the programmer, to be placed in the keyboard buffer.  This
     happens when:

     .  Data arrives at the port.

     .  A transmission error or a BREAK is recognized in the LSR.

     .  One of the signals in the MSR changes.

     .  The receiving buffer becomes 75% or more full.

     The MSR and LSR status, the number of errors that have already occurred,
     and the receipt of individual characters can be monitored through the
     <nKeyValue1> key code.  All information is saved in an internal memory
     area and can be queried from there using the COM_EVENT() function.  This
     procedure is important because the register or the flags that release
     the interrupt, are automatically reset during read access.  Otherwise,
     the information is lost.

     If the <nKeyValue2> parameter is specified, then one more procedure can
     be specified using the SET KEY TO command when the receiving buffer is
     75% or more full.  If the <nKeyValue2> parameter is specified, the
     <nKeyValue1> key code is no longer placed in the keyboard buffer when
     characters are received.  However, you can still monitor the MSR and
     LSR.

 Notes

     .  The status of the various interface registers are connected to
        the internal memory for as long as the event is "serviced" by a new
        COM_KEY() function call.  This means that the modifications made
        during this period cannot be lost.

     .  COM_KEY must be newly activated after every executed trap.
        This deletes information concerning the internal environment.

     .  When COM_KEY() places a character into the buffer because the
        buffer is close to full, it does so independently of the COM_SOFT()
        or COM_HARD() functions.

 Example

     CHR(227) is placed in the keyboard buffer and calls the COMERRORS
     procedure if an error is recognized at port 2 or if the modem status
     signal changes.  As soon as the buffer is 75% full or more, CHR(228) is
     placed in the keyboard buffer.  When CHR(228) is placed in the keyboard
     buffer, the BUFFERFULL procedure is called:

     #include CTCOM.CH                   // Symbolic constants
                                         // for interface
     COM_OPEN(2, 1000)                   // Open COM2
     CON_INIT(2, 1200, "N", 8, 1)        // Initialize COM2

     SET KEY 227 TO ComErrors
     SET KEY 228 TO BufferFull

     COM_KEY(2, 227, 228)                // Monitor COM2

     cName  :=  SPACE(20)                // The port can arrange
     PROCEDURE COMMERRORS(A, B, C)

        nMSR_Status  :=  COM_EVENT(2, 2) // Read accumulated
                                         // MSR data

        nLSR_Status  :=  COM_EVENT(2, 2) // Read accumulated
                                         // LSR data
        COM_KEY(2, 227, 228)             // Reactivate traps, reset
                                         // internal values of COM_EVENT

        IF ISBIT(nMSR_Status, MSR_RI)          // Ring bit set?
           ? "Call (ring) acknowledged!"
        ELSE
           IF ISBIR(nLSR_Status, nLSR_Break)   // Break bit set?
              ? "Break acknowledged!"
           ENDIF
        ENDIF
        RETURN
     PROCEDURE BUFFERFULL(A, B, C)

        * The input buffer must be read!
        COM_KEY(2, 227, 228)                 // Traps activated here
        cData  := COM.READ(2)                // Read all data
        SELECT MESSDAT
        REPLACE ComDat WITH cData            // Save data
        SKIP
        SELECT INPUT
        RETURN