Preliminary Documentation for GATE May 8, 1985 by Charles E. Owen, Jr. GATE is the Generalized Asynchonous Terminal Emulator, a program to allow CP/M-80 based systems to emulate almost any commonly used asynchonous terminal from most manufacturers. GATE provides "translation", through the CPU, between a local terminal and a remote system so that the local terminal (of whatever kind) appears to be the type of terminal the remote is expecting. This includes cursor controls and special features such as dim, blink, underscore, and other common features. The author places GATE in the public domain, and it may be freely distributed to any end user who wants it. The only restriction is that GATE may only be USED by end users, not sold for profit. Features * Full or half duplex terminal emulation. * Translation of cursor and special feature control sequences between the local terminal and the remote system (Optional). * Optional logging of the remote system's output to a disk file. * File transfer options to send CP/M files to the remote system under four different protocols (more to be added later!). * User definition of terminal attributes so the user can add to GATE's "library" of terminals. ********** This preliminary version of GATE has been tested in a CP/M-80 environment with several terminal types of varying kinds (ANSI standard, SOROC, LSI, NCR, DG & others) as both local and remote terminals. There may be some glitches and omissions in the Terminal Definition Block (described in detail later) which will be corrected later in the "official" version 1.00. But this version should be very useful and any users are encouraged to report problems or suggestions to the author at (919) 692-3016 (work) or (919) 692-8615 (home) any time. DISCLAIMER This program is provided strictly on an "AS-IS" basis only. No liability whatever can be accepted by the author for any damages arising from the use of this program or documentation. No warranties of any kind, expressed or implied, are granted to any user of this program or documentation. GATE Preliminary Documentation 05/08/85 Page 1 A tiny bit of history: GATE originated at the author's place of business (Systems Unlimited, Inc.) because our applications packages are written in a machine-independent style of COBOL, and hence are installed on a wide variety of Mini- and Microcomputers. We do most program support via modems, and to save the expense of buying otherwise useless terminals from the computer companies whose equipment we run on we wrote GATE. While most publicly-accessed bulletin boards deliberately avoid using any terminal's special features, many programs running on remote systems different from your own take full advantage of a particular terminal's features -- and if you don't have a compatible terminal, you're out of luck. Except for graphics (which it can't handle) GATE will solve this problem for you. Even if the terminal you want to emulate isn't in GATE's terminal library (GATE.DAT) you can add it easily if you know the binary control sequences for its special features. Currently, only this CP/M version of GATE is available. However, if GATE proves useful in the public domain, the author plans to publish other versions for MS-DOS and other operating systems. In addition, at a later time a more "user-friendly" GATE may be available that will contain interactive terminal re-configuring and an internal telephone directory. Customizing GATE ---------------- To operate GATE, you only need the GATE.COM file. This contains all the program code necessary, plus definitions of two terminals in areas called "terminal definition blocks". These two terminals are referred to as the "Local" and "Remote" terminals. The Local terminal is the one connected to your CP/M system, and the Remote is the type of terminal the remote CPU expects to be communicating with. In order for GATE to communicate with your remote terminal, at least the terminal definition block for the remote system must contain the proper I/O addresses to interface with your I/O board. These are the addresses within GATE.COM to patch: Address (HEX) Contents Meaning ------------- -------- ------- 310 12 I/O port of status channel 311 13 I/O port of data channel 312 2 Mask for transmit register ready 313 1 Mask for input character ready 314 12 I/O port for board/terminal init 315 2 Number of initialization bytes 316 3 First terminal initialization byte 317 11 Second terminal init byte 318-335 0 30 more bytes for initialization (all nulls in standard version) If changing these addresses does not render your remote terminal operational (and there are several possible reasons: memory-mapped terminals or I/O ports, more than one mask required, etc) you can provide your own initialization and I/O routines as described later in this document. GATE Preliminary Documentation 05/08/85 Page 2 The standard GATE.COM program is distributed with both the local and remote terminals defined as ANSI standard terminals, for lack of any more likely combination. Since this is probably not the environment you will be using GATE in, you will also need the GATE.DAT file. GATE.DAT is a file of 256-byte Terminal Definition Blocks for several commonly used terminals. If you elect to Redefine either of your terminals when you run GATE (see below for operating instructions) the GATE.DAT file will be read into memory and used to display a menu and permit selection of the different terminal types for local or remote definitions. You can modify or add to the GATE.DAT file if you have a CP/M assembler handy. Instructions on how to do this, and also an explanation of the fields in the Terminal Definition BLock are provided later in "Defining your own terminal". After you have patched the GATE.COM file, you will want to save it with your patches. Simply type SAVE 24 GATE.COM to do this. Operating GATE -------------- To execute GATE, simply type GATE at the CCP prompt. The program will load, and display a menu of options. This is an explanation of each of the options: (L)og data in buffer Pressing L will toggle this option. Initially it is OFF in the standard GATE. When the option is ON, all data bytes received from the remote system will be logged in a memory buffer, whose size is shown in the next option. When OFF, no bytes are logged, but any previous bytes recorded are still held in the buffer. You may Clear this buffer using the C option below, or Write it to a disk file with the W option, below. NOTE: When the terminal translation option is in effect, terminal special control sequences that are translated from the remote to the local terminal are NOT logged in this buffer. This prevents "clutter" from cursor positioning or special attributes from messing up any data you may want to capture. (C)lear buffer Press C will clear the logging buffer by setting it to all EOF codes (1AH). The "total bytes logged" count in the next option will revert to 0. (W)rite buffer to file Pressing W means you want to write the entire contents of the logging buffer to a disk file. You will be prompted for the file name, which must not already exist. Writing the buffer does NOT clear it automatically. The resulting disk file will contain the number of bytes shown in the "Total Bytes Logged", padded with EOF (1AH) characters. GATE Preliminary Documentation 05/08/85 Page 3 (F)ile transfer to remote system Use this option to send a disk file from your CP/M system to the remote system byte-by-byte in a serial stream. This option currently supports only ASCII file transfers, but later versions of GATE will support XMODEM and other protocols. You will be prompted for the file name to transmit, which you enter in standard CP/M file name format (A:FILENAME.EXT). The file must be an existing, online, ASCII sequential file. You will then be prompted for the "mode". Each is explained below. 1) ASCII Text file with no options This will simply pump your data out to the remote system byte by byte as fast as possible. Transmission will end if you press CONTROL-X or at the end of file. The drawback to this method is that frequently the sending machine (yours) sends data faster than the receiving machine can process it, since the receiver must pause every once in a while to write it's data to disk. If it pauses while you are sending data, data will be lost. Some systems are interrupt driven and allow type-ahead on their terminals, so no characters will be lost even while the CPU is doing somthing else. If this is the case, you may be able to use this option. 2) ASCII Text with delay after each line This option addresses the problem of speed mentioned above, but not in an entirely satisfactory way. Using this method, the sending CPU delays after each line for about 1/4 of a second to allow the receiving CPU to keep up. But, if the receiver does not pause exactly when the sender is waiting, data will still be lost, plus you will have a slower transmission due to all the wasted delays. The primary use for this option is when sending to interrupt-driven systems where buffer overflow is occuring in the receiver. This will slow down transmission so the receiver's interrupt handler can keep up. 3) ASCII Text file with XON/XOFF This is a commonly used, simple protocol that solves the problem of synchronization between sender and receiver without unnecessary delays. The sender sends data to the receiver as fast as possible until the receiver sends an "X-OFF" character (CONTROL-S or 13 hex) to indicate it's buffer is full. The sender then waits until an "X-ON" (CONTROL-Q or 11 hex) is received to start transmitting again. Several minicomputers use this protocol. GATE Preliminary Documentation 05/08/85 Page 4 4) ASCII Text with BELL prompt. This is another method that can be used with systems that do not support XON/XOFF. The sender sends the first line of text, when waits until the receiver sends a BELL character (CONTROL-G, or 7 hex) to send the next line. Each line is sent only after receiving a BELL from the receiver. Examples of using this are sending to NCR minicomputers, where the terminal beeps when it is ready for each line, or sending to PRIME computers, where the EDitor can be instructed to use a BELL as the input prompt character. (The SOURCE, for example, uses the PRIME editor). After you select the protocol, you are asked Do you want to send NEWLINE after CR? [N] Since you are transferring data line by line, the CR (carriage return, 0D hex) key is sent to terminate each line. Normally, even if your data file (as is normal on CP/M systems) contains a NEWLINE character (0A hex) after each CR in the disk file, you don't want to also send that NEWLINE to the remote system. Because most systems will recognize both CR and NEWLINE as line terminators, and this will result in an extra blank line after every good line in the resulting file on the receiving system. But by selecting "Y" to this question, you can elect to send the NEWLINE after the CR anyway (some systems may ONLY recognize NEWLINE as an end of line character, for example). After selecting this, your data will be sent from the disk file to the remote system just as if it were typed in on your keyboard, only at a much faster rate. You can interrupt the transmission at any time by pressing CONTROL-X on your keyboard. After tranmission has ended, you will be asked: End of file. Transmit EOF (1AH) to remote system? [N] If the program that is receiving your data on the remote system expected an EOF code to tell it the transmission is completed, enter "Y" in this option. If some other code is required, enter "N", then use the Emulator to manually type in the end of file code to the remote system. NOTE: These file transmit options DO NOT do anything special to set up a receiving program on the remote system, or to terminate transmission other the sending the optional EOF code. You must use the emulator to invoke any receiver programs (such as a text editor) on the remote system BEFORE you start your transmission. GATE Preliminary Documentation 05/08/85 Page 5 (T)ranslate terminal controls The major power of GATE is it's ability to emulate many different terminals without backbreaking effort. Pressing T toggles the Translate option, initially set OFF, to allow translation of special control sequences between the local and remote terminals. IF this option is OFF, no translation is done -- characters received are passed on to the local terminal "as is". If this option is ON, incoming characters are searched for special codes (defined in the Terminal Definition Block) and if a special code (or sequence of codes) is received, it is translated to the equivalent sequence for the local terminal. Keys pressed on the local terminal are translated to their remote system equivalents if necessary. This option is automatically turned ON if you Redefine either of the Local or Remote terminals using the R option below. (S)et terminal duplex mode. Initially when GATE comes up, it assumes full duplex communications with the remote (this is, characters pressed on the local keyboard are not automatically echoed on the screen. Any echo will come from the remote system). Pressing S will toggle this option to HALF duplex. (R)edefine terminal types. You can see the terminal types for the local and the remote terminals on the two lines below. Pressing R allows you to select other terminal types for both the local and remote terminals. When you press "R", GATE will see if the GATE.DAT file exists in the current directory. If it is not there, you cannot redefine any terminals, and an error message will display. Otherwise, the definitions in the GATE.DAT file are loaded into an internal buffer and displayed in a menu for your selection. If the buffer has already been loaded, the GATE.DAT file is not accessed. Simply select the terminal type you want by entering its number. When you do this, the program will ask if you are redefining your Local or Remote terminal. You may need to load definitions of one or both of these, but when you do GATE will return to its first menu, where you will see your selections shown as the current terminal types. You may want to save this version of gate permanently so you will not have to do this selection each time you bring it up. We recommend you save it under another name, however, to preserve the "purity" of the original version. To save it, select Q and then enter "SAVE 26 NEWGATE.COM" in the CCP. NEWGATE.COM will contain a "tailored" version for GATE for you. You may need to save more than 26 pages if you have more than 4 terminals in your table. Add 1 page for each new terminal you define. GATE Preliminary Documentation 05/08/85 Page 6 (E)nter terminal emulation mode When you select E, the screen is cleared (if the proper terminal type has been selected for the local terminal) and you are communicating with the remote system via the I/O ports you patched in during the customization step. Keys you strike on your keyboard are sent to the remote system (with translation if needed and that option is ON), and characters received from the remote are displayed on your terminal (also with translation if appropriate). Received characters are logged in the internal buffer if the logging option is ON. If things do not happen as expected (for example garbage rather than formatted data is displayed) you may have selected an inappropriate terminal type for either the local or the remote, or some attributes in the terminal definition block(s) are invalid. If nothing happens, either you have selected incorrect hardware interface options in the customization step, or the remote system is not communicating due to it's own problems. TO GET OUT of terminal emulation mode, strike the INTERRUPT key. This is a special key (which may be different depending on the terminal definition blocks) which signals GATE to return to it's main options display and stop emulating. This is so you can change options, save the buffer, or whatever. The interrupt key on most terminals sent with standard GATE is the backwards apostrophe: "`". This is a character rarely used (since it cannot be sent to the remote). You can change this (and other keys) in the terminal definition block (see the next section). (Q)uit GATE and return to the operating system Press Q to leave GATE and return to the CP/M CCP program. GATE Preliminary Documentation 05/08/85 Page 7 Defining your own terminals. --------------------------- Supplied as a part of the GATE package is a CP/M assembler file called "TERMS.ASM" which was used to produce the GATE.DAT file containing the terminal definition blocks. You can modify, or add to, this file to produce a new GATE.DAT file with "Customized" terminal configurations. Use this procedure to add a new terminal definition to the GATE.DAT file: 1. Use ED or another editor to edit the TERMS.ASM file. Pull in the TDB.LIB file provided with the GATE package into the TERMS.ASM file just before the END statement at the end of the source. Mass change the FQ in front of every field name to a two-character code of your choice that does not conflict with previously-defined blocks. 2. Using a chart of the control codes and sequences for your new terminal, plus the terminal definition block documentation covered next, modify the null attributes in the new TDB to match your terminal's characteristics. 3. Assemble the new TERMS.ASM file with the CP/M standard assembler (or another if you prefer). Check to be sure that the next available address shown after assembly is on an even 256-byte boundary (i.e. 600 hex or 700 hex or any hex number ending with 00). This is because each TDB in the file is 256 bytes long. If the ending address is not an even multiple of 256, you have defined one or more attributes with too many (or too few) bytes. 4. LOAD the .HEX file (if using CP/M ASM) or link if using another assembler. The result is the TERMS.COM file. 5. Rename TERMS.COM to GATE.DAT -- You are ready to try it. 6. Bring up the virgin copy of GATE (one that hasn't been saved with the terminal definition buffer loaded). When you select "R", the new GATE.DAT file will be loaded into the buffer and you will be able to select your new terminal for testing. GATE Preliminary Documentation 05/08/85 Page 8 Explanation of the Terminal Definition Block -------------------------------------------- Field Offset Size Description..................................... Name (HEX) (DEC) FQNAME 0000 16 Name of the terminal being defined. The following 8 fields are "hardware interface" fields, which should be left NULLS to allow the interface information already patched into GATE.COM to remain in effect. If however you want to override GATE's patched-in interface, you can define one here in these fields. FQSTAT 0010 1 I/O Port to receive status information on FQDATA 0011 1 I/O Port to receive/transmit data characters FQXRDY 0012 1 Mask that when ANDed with status port will be NOT ZERO when the port is ready to transmit a character FQRRDY 0013 1 Mask that when ANDed with status port will be NOT ZERO when the port has a character ready to be read. FQINIA 0014 1 I/O port to transmit initialization characters to FQINIC 0015 1 Number of initialization characters to send to the Initialization port FQINIT 0016 32 The actual initialization bytes (up to 32!) The following 4 fields define basic characteristics FQLINE 0036 1 The number of lines on the terminal page (binary) FQCOLS 0037 1 The number of columns on a terminal line (binary) FQBREK 0038 1 The INTERRUPT key to break out of emulation mode. FQFNUM 0039 1 Number of special sequences defined below (usually 32) The following 32 fields are 4-bytes strings defining special terminal control sequences. Each field has the first byte being the number of bytes in the sequence (1 thru 3) if the first bytes is zero there is no equivalent sequence for that terminal. The next 3 bytes contain the sequence of characters. Each sequence defined here must be unique -- or the second occurance of a non-unique code will NEVER be accessed. FQBELL 003A 4 Ring bell on terminal FQBLKD 003E 4 Disable any blinking fields (stop blinking) FQBLKE 0042 4 Enable any blinking fields (start blinking) FQBLK0 0046 4 Blink off (stop a blink field) FQBLK1 004A 4 Blink on (start a blink field) FQDIM0 004E 4 Dim off (Stop a dimmed field) FQDIM1 0052 4 Dim on (start a dimmed field) FQEOL 0056 4 Erase to end of current line FQEOS 005A 4 Erase to end of entire screen (from current position) FQREV0 005E 4 Stop reverse video field FQREV1 0062 4 Start reverse video field FQUSC0 0066 4 Stop underscored field FQUSC1 006A 4 Start underscored field FQCON 006E 4 Turn cursor on FQCOFF 0072 4 Turn cursor OFF 0076 28 Space for future function definitions (reserved 7 fields) GATE Preliminary Documentation 05/08/85 Page 9 FQANSI 0092 4 Sequence that is the "Control Sequence Introducer" for an ANSI standard terminal control sequence. Support for most ANSI standard functions is built-in to GATE. IF the terminal will support ANSI standard, put it's here. IF not, leave this NULLS. FQCLR 0096 4 Clear screen and home cursor FQCURD 009A 4 Move cursor down 1 position FQCURH 009E 4 Move cursor to home position (line 1 col 1) FQCURL 00A2 4 More cursor left (backwards) 1 space FQCURR 00A6 4 Move cursor right (forwards) 1 space FQCURU 00AA 4 More cursor up 1 line FQSETL 00AE 4 Lead-in code for following byte or bytes to directly load the LINE number to position the cursor FQSETC 00B2 4 Lead-in code for following byte or bytes to directly load the COLUMN cursor position FQCURP 00B6 4 Lead-in code to indicate the following bytes are to directly load both LINE and COLUMN The following fields are used to select special options concerning the format of cursor addressing data. FQSETT 00BA 1 Format of the code for directly setting the LINE number (when triggered by FQSETL above): 0 = line number is BINARY 1 = line number is Binary Code Decimal in 1 byte FQSET2 00BB 1 Format for COLUMN direct setting (same codes as in FQSETT above) FQSETN 00BC 1 Number of bytes in direct set cursor codes (normally 1 for binary or BCD, 2 for decimal or hex) FQCADJ 00BD 1 Adjustment factor for binary cursor addresses. The value in here is ADDED to the binary line & column addresses for cursor positioning. Also, very important, the high bit of this field selects the FORMAT of the direct cursor address: 0 = line number (row) is first, then column number 1 = column number is first, then row number FQCSEP 00BE 1 Number of pad bytes between row and column addresses (normally this & the next field are zero) FQCTRL 00BF 1 Number of pad bytes following the cursor address. The following fields define special codes for keyboard functions. They are used to translate keys pressed on the local terminal to equivalent keys to trigger functions on the remote system. FQKDL 00C0 1 Key meaning "delete line" FQKDC 00C1 1 Key meaning "delete character" (rubout) FQKFS 00C2 1 Forward space key (right arrow) FQKBS 00C3 1 Back space key (left arrow) FQKUD 00C4 1 Cursor down key (down arrow) (sometimes NEWLINE) FQKUU 00C5 1 Cursor up key (up arrow) FQKESC 00C6 1 ESCAPE key (normally ASCII escape: 1B hex) FQKBT 00C7 1 Back tab key (some terminals do not have this) FQKFT 00C8 1 Tab key (normally 09 hax) FQKCR 00C9 1 Carriage return key (normally 0D hex) FQKNL 00CA 1 NEWLINE key (normally 0A hex) GATE Preliminary Documentation 05/08/85 Page 10 FQF1 00CB 4 Function key #1 FQF2 00CF 4 Function key #2 FQF3 00D3 4 Function key #3 FQF4 00D7 4 Function key #4 FQF5 00DB 4 Function key #5 FQF6 00DF 4 Function key #6 FQF7 00E3 4 Function key #7 FQF8 00E7 4 Function key #8 FQF9 00EB 4 Function key #9 FQF10 00EF 4 Function key #10 SPACE FROM 00F0 THRU 00FF IS RESERVE FOR WORK SPACE. Providing User-written I/O routines ----------------------------------- GATE is designed to provide a general-purpose hardware interface in it's in-line code, so you only have to patch a few bytes to obtain a working version. But if your I/O interface is too complex for this simple system, you may need to provide your own drivers. At the very beginning of GATE a jump table is constructed to allo you to patch in your own I/O routines: Address (HEX) Jump vector to this routine: 0103 Routine to initialize the Local terminal 0106 Routine to initialize the Remote terminal 0109 Routine to test for a ready character from the Local terminal. Returns Zero flag reset (NZ) if a character is ready to read. 010C Routine to test for a ready condition on to transmitter to the Local terminal. Returns the Zero flag reset (NZ) if ready to transmit 010F Routine to read a byte from the Local terminal and pass it in the Accumulator. 0112 Routine to take a input byte in the C register and write it to the Local terminal. 0115 Routine to test for a ready character from the Remote terminal. Returns Zero flag reset (NZ) if a character is ready to read. 0118 Routine to test for a ready condition on to transmitter to the Remote terminal. Returns the Zero flag reset (NZ) if ready to transmit 011B Routine to read a byte from the Remote terminal and pass it in the Accumulator. 011E Routine to take a input byte in the C register and write it to the Remote terminal. 0121-01FF Space to code your own I/O routines in. 0200-02FF Terminal Definition BLock for the Local Terminal 0300-03FF Terminal Definition BLock for the Remote Terminal GATE Preliminary Documentation 05/08/85 Page 11