cvt100.doc

                     CVT100, Terminal Emulator for Turbo C





















                 VT100, A Simple VT100 Emulator in Turbo C 1.5
                        By Jerry Joplin CIS [70441,2627]










































                     CVT100, Terminal Emulator for Turbo C


                                    Overview


              CVT100 is a simple VT100 emulator programed exclusively
         in Turbo C 1.5.   *All* of the code is in Turbo C.  There are
         no assembler routines or functions requiring an assembler.
         All of the code is contained in 7 modules.  These are:

              comio.c       communications functions
              cvt100.c      terminal emulator main
              fileio.c      file manipulation functions
              keyio.c       keyboard functions
              vidio.c       video functions
              vtsetup.c     setup functions
              vttio.c       terminal output interpretation functions

         The program was designed with several objectives in mind.

              1)  To provide a public domain source for a VT100
                  emulator written in Turbo C code that was easy to
                  understand and modify,

              2)  To show the power and flexibility of Turbo C without
                  having to resort to assembly language routines,

              3)  To aid (however slightly) in the development of a C
                  version of Kermit for MS DOS systems,

              4)  To provide a terminal emulator that takes a very
                  small amount of memory and is capable of running in
                  a well behaved window in Windows or DesqView (less
                  than 40k).































                     CVT100, Terminal Emulator for Turbo C


                                   Operation

              The terminal emulator is menu driven.  The top line of
         the terminal screen is reserved as a status line.  A list of
         choices is displayed on the status line for setting the
         various parameters concerning the different aspects of the
         programs operation.

              Function Key F5:  This activates the Communications menu
                                setup. Here the COM port is
                                established along with its associated
                                baud rate, parity, data bits
                                and stop bits.


              Function Key F6:  This key will activate the Video setup
                                menu.  Here the screen colors can be
                                set and the "snow" inhibit mode can be
                                set.

              Function Key F7:  This key when pressed enters the
                                keyboard setup menu.  Here the
                                program's interpretation of the
                                backspace key can be set.  The
                                keyboard can be programed to produce a
                                'key-click' and the state of the
                                keypad can be defined.

              Function Key F8:  An Emulation menu becomes active when
                                F8 is pressed.  Here the many mode
                                settings for the emulator may be set.
                                These include origin mode,
                                insert/replace mode, auto wrap mode,
                                new line mode, cursor visibility,
                                background video attributes and the
                                logical screen width.

              Function Key F9:  Function key F9 brings up a File menu.
                                The current settings for the terminal
                                can be saved in an initialization file
                                that is read when the program is
                                started.  Also a log of incoming
                                characters can be controlled.

              Function Key F10: This is used as the exit key.  When
                                pressed this will close any open log
                                files and exit.
















                     CVT100, Terminal Emulator for Turbo C


                                 Communications

              Characters are received via receiver interrupts
         generated by the UART.  The interrupt service routine (ISR)
         for the incoming characters is a function of type interrupt
         for Turbo C.  Although any serious communications program
         should have the transmission interrupts in assembler, this
         program has been tested at 19,200 baud on a plain vanilla
         4.77 Mghz PC with no loss of characters.

              An XON/XOFF 'handshake' is used to control the flow of
         characters to and from the host.  An XOFF is transmitted to
         the host when 75% of the communications circular buffer is
         full.  This will tell the host to stop transmitting
         characters until an XON is transmitted to it.  When the
         buffer is back down to 25% full an XON will be sent to the
         host signaling it that it is okay to begin transmission
         again.

              When an XOFF has been received from the host this
         program will delay for a short period of time before sending
         a character to check for an XON being sent.  Note that the
         character will still be transmitted if the wait period passes
         with no XON being received.







































                     CVT100, Terminal Emulator for Turbo C


                                     Video

              Most video manipulations are done by reading and writing
         directly to the screen's memory.   This made it necessary to
         provide "snow" protection on CGA systems, but much less time
         is wasted on writing characters and attributes than using the
         BIOS.

              A check is done before each video memory access to
         detect a control program such as Windows, DesqView, or
         TopView.   Each of these control programs will keep a video
         "shadow" buffer for processes currently executing.  The
         address of this buffer can be queried and output directed to
         this buffer instead of the actual screen.  This will let
         CVT100 run in a well behaved window in these environments.

              There are several problems with the video system. A few
         of the colors (Yellow foreground) do not work properly with
         the emulation.  The program tries to juggle various
         attributes defined by the host's control commands and tends
         to lose the defined color in the process.  Also changing the
         screen foreground and background colors may or may not work
         during program execution.  This is due to the fact that the
         software tries to retain the contents of the terminal screen
         while making the color changes and again may get confused by
         defined attributes.  To get around this problem, exit the
         emulator and re-execute it.  The new colors will take effect
         properly upon video initialization.



































                     CVT100, Terminal Emulator for Turbo C


                                    Keyboard

              The most controversial part of any terminal emulator
         will usually be the setup of the IBM PC keyboard to try and
         match the Digital Equipment Corporation VT keypad.  Not an
         easy task.  This program tries to map as closely as possible
         the keypad for an IBM PC to a DEC VT keypad.   The results
         are often better if NUM LOCK is left on through out the
         entire session.

              If you are unsatisfied with the layout of the keyboard
         there are currently no means to assign keys any differently,
         but that is why the source is provided with this program!
         Check module KEYIO.C for changing the default setup.

















































                     CVT100, Terminal Emulator for Turbo C


                                   Emulation

              This program can best be described as a compromise
         between the desire to make the code as simple and straight
         forward as possible and the complexities and intricacies of a
         real life DEC VT100.  So many things were left out of the
         terminal emulation.

              Of the things left out of the emulation most notable
         will be printer output commands and double high/width
         character lines.  Local echo is also absent.

              The emulator can not change the video from 80 to 132
         columns and vice-versa when these commands are received from
         the host.  The commands are received and recognized but it
         only changes the logical width of the screen held by the
         emulation software.  It seems as if every video board
         manufacturer that has a board capable of switching to 132
         column mode has a different method of changing into this
         mode.  However this mode can be utilized by setting the
         screen to 132 columns *before* executing the program.  Then
         the video system of the emulator will properly use all of the
         columns.








































                     CVT100, Terminal Emulator for Turbo C


                                  File System

              The setup information can be saved to a disk file when a
         satisfactory setting has been reached.  When the program is
         executed it looks in the current directory for this file
         named 'CVT100.SET' from which to load the setup parameters.
         If this file is not found then default values are provided.
         Currently the only way to have multiple setups is to have
         them in separate directories that the program can be executed
         out of.

              Incoming characters can be logged to disk.  When logging
         is selected then all incoming characters are saved in a disk
         file names 'CVT100.LOG'.  If a file by that name exists at
         the time when logging is selected then output is appended to
         this file.  If no file is present when logging is selected
         then a file will be created in the current directory.  Note
         that *no interpretation* is performed on the characters
         placed in the disk file.












































                     CVT100, Terminal Emulator for Turbo C


                              Program Termination

              Any time the program is exited the communications port
         will be closed to prevent incoming characters generating
         interrupts to ISR's which don't exist in memory any longer.
         Additionally the log file will be closed if it is open on
         program exit.

              There are several errors which may cause the emulator to
         force itself to exit.  If memory can not be allocated from
         the DOS heap for the screen save buffer then the program will
         be terminated with an error message.  Also the file IO
         functions may terminate the program if a system error has
         occurred on a read or write of a disk file.  This could be
         caused by a disk full error or fault media.   *CAREFUL*
         because the program does not currently trap the fatal error
         interrupt and disk errors will produce the not-too-kind error
         message:

                  Not ready error writing drive A:
                  Abort, Retry, Ignore?

         Choosing Abort will cause the terminal to exit without having
         turned off communications interrupts.  This will cause a
         quick system lockup if a character is received by the UART.






































                     CVT100, Terminal Emulator for Turbo C


                                    Testing

              The emulation has been tested primarily on 2 systems.
         The first and most important was a Digital VAX running VMS.
         There are several utilities running under VMS that try even
         commercial VT100 emulators.  Most notable of these utilities
         is the VAX TPU editor,  thus importance was given to getting
         this version of a VT100 emulator working under the VAX TPU
         editor as well as the EDT editor provided with VAX VMS.
         Other exceptionally difficult programs to get an emulator
         running under were the VAX/VMS debugger in full screen mode,
         VAX/VMS mail, and programs using the VAX/VMS FMS screen forms
         manager.

              Extensive testing was also done on the free practice
         forum on CompuServ. (GO PRACTICE, I even got a good working
         knowledge of the new SIG forum commands)   This turned out to
         be a piece of cake after working with many of the VAX/VMS
         programs.  As far as I can tell the CompuServ host computers
         will only send cursor addressing commands and screen clearing
         commands to terminals set up to be VT100's.  Therefore if
         your terminal is set up to be an 80 X 24 VT100 to CompuServ
         (GO TERMINAL) this VT100 emulator will provide thorough
         terminal emulation.







































                     CVT100, Terminal Emulator for Turbo C


                                Acknowledgments

              The VT100 emulation is based heavily on two versions of
         Kermit.   The most notable version of Kermit was MSKermit
         version 2.30 written in Microsoft Macro Assembler 3.0.
         CKermit for Unix was also used for program design and
         nomenclature.  Therefore this Copyright appears as required.

                              Copyright (c) 1981, 1988
              Trustees of Columbia University in the City of New York

              Permission is granted to any individual or institution
              to use, copy, or redistribute this program and
              documentation as long as it is not sold for profit and
              as long as the Columbia copyright notice is retained.

              This program would have never got off the ground if it
         was not for the work put into a VT102 emulator written
         primarily by J. R. Doupnik of Utah State University for
         MSKermit.  Many other people have worked on MSKermit,
         including Frank da Cruz and Christine Gianone of Columbia
         University.  A list of these people would have been
         incomplete and is not attempted here though their
         work has been appreciated greatly by me over the years. If
         any questions came up regarding a particular facet of VT100
         emulation I would always refer to the MSKermit version 2.30
         assembler source code.  The assembler source to MSKermit also
         served as a design outline, although it was difficult to
         maintain much of this outline in a conversion from assembler
         to C.

              I also referred many times to a version of CKermit for
         Unix systems.  Although there is no terminal emulation code
         supplied with this version of Kermit, it helped in the
         general design layout of the source modules and also helped
         with the function naming conventions used by this program.
         In fact it was my original intent to get a version of CKermit
         going for MS DOS systems I now understand someone has already
         done this somewhere.