Contents of the CVT100.DOC file

CVT100 is a simple VT100 emulator programmed exclusively in Turbo C 2.0. *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:

This is version 2.0 of the CVT100 emulator. Version 1.0 of the emulator was designed with the following 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 Vers 2.0 was aimed at 4 additional objectives:

5) Optimize the performance of the video system for operating environments such as MS Windows and DesqView.

6) Provide public domain code showing a method of designing a program achieving optimum output under MS Windows or DesqView without sacrificing performance as a standalone program under DOS.

7) Fix several bugs in the first version of CVT100.

8) Add a compile time DEBUG option that allows input to the communications system to be taken from a FILE rather than received characters from the communications port.

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 programmed 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.

Version 2.0 of CVT100 also adds a debugging feature in the communication system. Input can be taken from a file and interpreted as received characters. Debugging is enabled by a #define DEBUG in module COMIO.C.

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.

Not only will CVT100 run in a well behaved window, but CVT100 version 2.0 was designed to provide excellent performance under these operating environments. CVT100 uses a simple character output buffering scheme. This scheme improves the performance under MS Windows by %400 while hardly changing operation under DOS alone.

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.

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.

Special thanks to Bill Wood who located an error in the video system of CVT100 version 1.0. Not only did he locate the error but also provided the code to fix the error! This fix is incorporated into CVT100 version 2.0.