Click above to get retro games delivered to your door ever month!

 Notifications

 Telepathy's notifications let a program process serial I/O in the
 background while performing normal user interaction in the
 foreground.  A notification request is like a SET KEY TO.  It tells
 Telepathy to watch for a certain event in the background, and when
 that event occurs, interrupt the foreground program to run an event
 handler.  Like the SET KEY TO method, notifications are normally only
 handled while the program is in an input "wait state".

 The functions that request notifications are:

 tp_onchar()     When a certain character is received.
 tp_onempty()    When the output buffer is empty.
 tp_onhimark()   When the input buffer is nearly full.
 tp_oninput()    When any character is received.
 tp_onmodem()    When a modem status signal changes.
 tp_ontime()     After a certain number of seconds.

 Since notifications use the same mechanism as SET KEY TO to work, any
 Clipper command that removes characters from the typeahead buffer can
 cause notifications to be "lost".  The major offenders are INKEY(),
 CLEAR TYPEAHEAD, and KEYBOARD.  Telepathy supplies functions which
 can be used in place of those commands to avoid problems:

 tp_inkey()      Replacement for INKEY().
 tp_clrkbd()     Replacement for CLEAR TYPEAHEAD.
 tp_keybd()      Replacement for KEYBOARD.

 [5.0] In Clipper 5.0, the header file tpkeybd.ch supplies command
 definitions to replace these commands with the Telepathy functions.

 Other functions related to notifications are:

 tp_delay()      Pause a specified number of seconds, processing
                 notifications.
 tp_noteoff()    Delete unactivated notifications.
 tp_suspend()    Suspend processing of notifications.
 tp_resume()     Resume notifications after tp_suspend().

 Once a notification event occurs and the event handler is called, the
 notification is deleted.  Unlike SET KEY TO, the notification must be
 requested again each time.  Usually the best place to do that is
 right in the notification handler.

 A total of 16 notification requests can be active at any one time.
 Also, there is a limit of 4 tp_onchar() notifications for any one
 serial port.

 Notification Handlers

 A notification handler is a user-defined procedure or function.  It is
 passed four parameters, though it can ignore them, and does not need to
 declare the parameters in its header if it does not use them.  The
 parameters are: the notification handle from the tp_on...() function
 call, a numeric code for the type of notification, the serial port
 number, and the character received.  The serial port number is omitted
 for tp_ontime(), and the character received applies only to
 tp_onchar().

 The notification handler declaration might look like this in Clipper
 5.0:

     procedure Notify(nNote, nCode, nPort, cChar)

 or like this in Summer '87:

     procedure Notify
         parameters nNote, nCode, nPort, cChar

 The possible values of the nCode parameter are:

     Value       Name            Meaning
     ----------------------------------------
       1         TN_ONCHAR       tp_onchar()
       2         TN_ONEMPTY      tp_onempty()
       3         TN_ONHIMARK     tp_onhimark()
       4         TN_ONINPUT      tp_oninput()
       5         TN_ONMODEM      tp_onmodem()
       6         TN_ONTIME       tp_ontime()

 [5.0] In Clipper 5.0, the constants in the "Name" column are defined in
 the telepath.ch header file.