KEYTIME()
 Triggers a key trap at a specific clock time
------------------------------------------------------------------------------
 Syntax

     KEYTIME([<nKeyValue>,<cClocktime>]) --> lActivated

 Arguments

     <nKeyValue>  Designates the character to place in the keyboard
     buffer.

     <cClocktime>  Designates the specified time to place the character
     in the keyboard buffer.

     ()  When called without parameters, the function completely uninstalls.

 Returns

     KEYTIME() returns a .T. to indicate the specified character was placed
     in the keyboard buffer at the desired time.

 Description

     Warning!  Use on AT-class systems only!

     KEYTIME() executes a specific program at an indicated time.  To do this,
     the function places the desired key code in the keyboard buffer at the
     selected clock time.  If a procedure is established with
     SET KEY..TO, CA-Clipper calls the procedure if, or when, you are in a
     wait state.  This allows you to perform specific tasks at a particular
     time of day such as file backups.

     There is also a special variant over and above an exact time
     designation.  You can specify "99" for hours, minutes, or seconds, which
     modifies the interpretation of this portion of the time designation.  A
     time string of "10:99:00" instructs the function to trigger a key trap
     every minute between 10:00 and 10:59.

     If you want to specifically uninstall the function from the program,
     call it without specifying parameters.

 Notes

     Warning!  Always uninstall the function before you leave the program
     or use the CTUS.LIB Extended Drivers found in CA-Clipper Tools.  This
     function changes the interrupt vectors, and if the previous status is
     not restored before you leave the program, a system crash will
     eventually occur.

     .  Only one time monitor can be active at any given time.  A
        subsequent call to KEYTIME() deactivates the previous one.

     .  You can use any symbols defined in the CA-Clipper file
        INKEY.CH.   You can set any other keys described in the CA-Clipper
        Tools header file CTSCAN.CH.

 Examples

     .  Place key code 7 in the keyboard buffer at 12:30:

        ? KEYTIME(7, "12:30:00")      // .T.

     .  Place key code 255 in the keyboard buffer at 2:00 PM:

        ? KEYTIME(255, "2")           // .T.

     .  Place key code 7 in the keyboard buffer at midnight:

        ? KEYTIME(7, "00:00:00")      // .T.

     .  Set a key trap every second, starting at 11:59 PM:

        ? KEYTIME(7, "11:59:99")      // .T.

     .  Set a key trap every full hour:

        ? KEYTIME(7, "99:00:00")      // .T.

     .  Call with an invalid time:

        ? KEYTIME(7, "25:30:00")      // .F.

     .  Uninstall KEYTIME():

        ? KEYTIME()                   // .F.