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

 Terminal Emulation

 These are the terminal emulator functions:

 tp_ansi()       PC ANSI terminal emulator.
 tp_tty()        Dumb TTY emulator.
 tp_vt102()      DEC VT102 terminal emulator.

 There are several additional functions that work together with the
 terminal emulators.  They are:

 tp_escseq()     Return last escape sequence.
 tp_tcol()       Return emulator cursor column position.
 tp_tcolor()     Control emulator display colors.
 tp_tflags()     Get or set emulator control flags.
 tp_tpos()       Set emulator cursor position.
 tp_trow()       Return emulator cursor row position.
 tp_tsay()       Write string to emulator window.
 tp_tsend()      Send character string.

 A terminal emulator combines two functions into one:

     It displays incoming text and other messages you specify in a
     window on the screen, handling control characters and escape
     sequences in the same way as a real terminal would.

     It sends characters typed on the keyboard out to the serial port,
     while letting the program handle special keys (function and
     cursor keys, Alt-key combinations).

 Telepathy's emulator functions can distinguish between all keys on
 the keyboard.  While control-C and PgDn have the same INKEY() values,
 they are different keys.  The emulators will send control-C
 keystrokes to the serial port, but let your program handle PgDn.

 Several cautionary notes are in order.  Terminal emulation accesses the
 computer's video display memory directly, bypassing Clipper's terminal
 output module.  It will only work on systems which are 100% compatible
 with some PC display hardware standard, such as CGA, MDA, Hercules,
 EGA, or VGA.  The emulation functions can be set to use the computer's
 BIOS rather than accessing display hardware directly, which may make it
 possible to use them on systems which are BIOS-compatible but not
 hardware-compatible.

 The terminal emulation functions also access the computer's keyboard
 BIOS directly, rather than using Clipper's keyboard input functions.
 This leads to potential conflicts with Clipper's keyboard buffer.  Keys
 placed in Clipper's buffer (using KEYBOARD) are NOT available to the
 terminal emulators.  Also, input waits in the emulators do not count as
 wait states as far as Clipper's SET KEY TO functions are concerned
 (although Telepathy notifications will be handled).

 In some cases, keyboard input will work better if you disable Clipper's
 typeahead buffer with SET TYPEAHEAD TO 0.

 Exception Handler

 While a terminal emulator is active, it calls a user-defined exception
 handler at various times.  The main use of the exception handler is for
 dealing with extended keys other than the plain ASCII keyboard, but it
 can do a number of other things.

 You pass the name of your exception handler to the emulator function.
 The exception handler will be called with two parameters: a numeric
 code for the current status, and an optional second parameter which
 serves various purposes depending on the status.

 Return Value.  The exception handler should normally return zero.  If
 it returns a non-zero value, the emulator function will terminate.  If
 the value returned from the exception handler is greater than zero, the
 emulator will return zero; if it is less, the emulator will return that
 value.  Negative return values are useful for flagging errors.

 NOTE: the exception handler return value is ignored for the TTY_COLOR
 and TTY_ESCSEQ messages.

 Parameters.  The exception handler function declaration might look like
 this in Clipper 5.0:

     function TermException(nCode, nParam)

 or like this in Summer '87:

     function TermException
         parameters nCode, nParam

 The possible values of the nCode parameter are:

     Value       Name            Meaning
     ----------------------------------------------------------------
       1         TTY_UNKEY       Unknown key.  Some non-ASCII key has
                                 been pressed.
       2         TTY_INIT        Emulator being initialized.
       3         TTY_WATCH       An input watch has matched.
       4         TTY_ERROR       A serial I/O error occurred.
       5         TTY_NORECV      Polling for input.
       6         TTY_COLOR       Display color has changed.
       7         TTY_ESCSEQ      Received unknown escape sequence.

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

 TTY_UNKEY.  nParam is the INKEY() value of the key.  Normally, this is
 any key with an INKEY() value less than 0, or greater than 255, but
 also includes the cursor keys (though NOT the control keys with the
 same INKEY() values).  If the TF_NOSEND flag is set by tp_tflags(),
 every key is considered "undefined", and will trigger this message.

 TTY_INIT.  nParam is 0.  This message is sent as soon as the emulator
 starts up, before it begins processing input or output.

 TTY_WATCH.  The emulator checks continuously for input watches using
 the tp_getwatch() function.  As soon as a watch string matches, it
 sends the exception handler this message.  nParam is the input watch
 handle.

 NOTE: Response to watches may not be instantaneous.  Depending on the
 baud rate, some additional input may be processed after the watch is
 hit and before the TTY_WATCH message is sent.

 TTY_ERROR.  Called when a serial I/O error occurs.  nParam is the error
 code.

 TTY_NORECV.  When the TF_NORECV flag is set by tp_tflags(), the
 emulator will not process any input.  Instead, it will send this
 message repeatedly, every time through its main loop.  The TTY_NORECV
 message can be used to poll for input in the exception handler.

 TTY_COLOR.  This message is used only if the TF_COLOR flag is set by
 tp_tflags().  It is sent when the display color changes because of a
 control sequence received by the emulator.  nParam is the numeric value
 of the color parameter being processed (e.g., 1 for bold or 4 for
 underlined with the ANSI or VT102 emulators).  nParam is -1 when the
 VT102 emulator receives a soft or hard reset command (which sets the
 display color to normal).

 At the time the TTY_COLOR message is sent, the text and background
 attributes have already been changed.  You can call tp_tcolor() from
 the exception handler to change them again to whatever values you
 prefer.

 TTY_ESCSEQ.  This message is sent when the emulator receives an escape
 sequence which it does not recognize.  You can use tp_escseq() to find
 out what sequence was received.

 The Emulator Cursor

 Terminal emulators keep track of their cursor position independently of
 Clipper.  While the emulator is waiting for input or writing to the
 screen, the positions are the same.  However, you can move the real
 cursor in the exception handler without changing the position of the
 emulator cursor.  As soon as the exception handler returns, the real
 cursor gets moved back to the same place it was when the exception
 handler was started.

 tp_tpos() controls the emulator cursor.  Given a row and column number,
 it moves the emulator cursor--but not the real cursor--to that
 position.  The position is measured relative to the top left corner of
 the emulator window, not the real screen.  tp_trow() and tp_tcol()
 return the current position of the emulator cursor, relative to the
 same window.  The standard Clipper commands for displaying and hiding
 the cursor (SET CURSOR and, in 5.0, SETCURSOR()) still work normally.