LC-Term Copyright (C) 1984 by Larry Campbell 73 Concord Street, Maynard, Massachusetts 01754 USA This document reflects LC-Term version 3.30. October 11, 1984 1 LC-Term LC-Term is a program that provides sophisticated terminal emulation and file transfer functions on a DEC Rainbow 100 or 100+ running MS-DOS. It requires 128K memory (192K or more for the PUSH function), and requires MS-DOS version 2.05 or later. LC-Term is unique among personal computer file transfer programs in that it supports both of the popular public-domain file transfer protocols: KERMIT and XMODEM. While XMODEM is more popular among microcomputer users, and supported by most public bulletin board systems, KERMIT is more frequently found on mainframes, and used for micro-to-mainframe communications. LC-Term supports both protocols, in one package. LC-Term is NOT in the public domain. See the section at the end of this document for copyright information. 2 Incompatible change in version 3.28 Starting with LC-Term version 3.28, in order to invoke LC-Term functions from terminal emulation, you must hold the CTRL key down while pressing the function key. For instance, to get the main menu, you hold the CTRL key down and press MAIN SCREEN. This change was necessary in order to provide VT2xx-family function key emulation. Pressing MAIN SCREEN (for example) without holding the CTRL key sends an escape sequence to the host that will be interpreted by - 1 - the host. 3 Running LC-Term Just type LCTERM to the MS-DOS command prompt. There are a few command switches that can be appended to the LCTERM command line: /8 In terminal emulation, pass all eight bits of terminal output to the display screen. This is required for displaying multinational characters. If the remote system generates parity, though, setting this switch will result in garbage on the screen. /t Bypass the top-level menu and go straight to terminal emulation. /s Open the file specified as a script, enter terminal emulation (bypassing the top-level menu), and process the script. - 2 - Note LC-Term asks MS-DOS what the switch character is (using DOS call 37 hex). The default is a slash "/", but this can be changed with the SWITCHAR= command in CONFIG.SYS. The most common alternative is hyphen "-", which makes MS-DOS look more like Unix. Note that this is an incompatible change beginning with version 3.02 of LC-Term. Earlier versions always used hyphen "-" as the switch character. 4 VMS KERMIT compatibility There is a bug in VMS KERMIT version 3.0.051 which is provoked by LC-Term (and also Unix KERMIT). The symptoms can vary, but all involve sending files from the VAX to the Rainbow. The sends fail in mysterious ways. The problem is related to the fact that LC-Term requests a 94-character packet size, while most other KERMIT implementations request a smaller one. To avoid this problem, if you're using version 3.0.051 of VMS KERMIT, then before using LC-Term to fetch a file from the VAX, give VMS KERMIT the command SET SEND PACKET_SIZE 90. 5 Menus LC-Term is menu-driven. This makes it easy to use most of LC-Term's features without reference to the documentation. Because the menus are intended to be self-explanatory (let me know if they're not), I won't describe them in detail here. I'll just briefly run over keyboard usage and terminology. Note At all times, the HELP key (CTRL-HELP during terminal emulation) will remind you what the currently available function keys are. If you're ever unsure what options are available, press HELP (or CTRL-HELP). - 3 - Whenever a menu is displayed on the screen, you may select items from the menu by one of three methods. You may use the up- and down-arrow keys to step forwards or backwards through the menus; you may enter the menu item number from the number keys on the main part of the keyboard; or you may enter menu item numbers from the numeric keypad. In all cases you must press the DO or RETURN key to activate the selected menu item. 6 Terminal emulation In terminal emulation LC-Term emulates a DEC VT102 terminal, and will identify itself as such in response to the terminal type inquiry escape sequence. (Actually, much of this emulation is handled by the Rainbow firmware.) In addition, function keys (the top row on the keyboard, and the editing keys above the arrow keys) are supported as if the Rainbow were a VT2xx-family terminal operating in 7-bit mode. During terminal emulation, the following function keys are available (you must hold down the CTRL key when pressing these keys): PRINT SCREEN Pressing this key allows you to copy the current screen to the printer or to a disk file. LC-Term prompts you for a filespec; if you just press RETURN, the screen is copied to the printer. When copying to a printer, LC-Term assumes it's talking to an LA50 or compatible printer; on other printers graphics characters on the screen may not be reproduced faithfully. INTERRUPT Pressing this key causes an "auto-push". LC-Term clears the screen, displays the message "Type EXIT to return to LC-term...", and loads and starts a copy of the MS-DOS command processor. You may now type any MS-DOS commands. LC-Term is still resident, and suspended. When you give the EXIT command, which stops the command processor, control is returned to LC-Term. The screen and cursor are restored, and you reenter terminal emulation. (Note: this feature, and the PUSH item available in LC-Term's top-level menu, require at least 192K of memory.) - 4 - EXIT Pressing this key causes LC-Term to exit to MS-DOS. MAIN SCREEN Pressing this key causes LC-Term to display its main menu. You may select options from this menu, and may return to terminal emulation by selecting item 1. In addition, you may define text strings to be associated with any of the function keys to the right of the main alphanumeric part of the keyboard, and certain top-row keys. This includes INTERRUPT through EXIT, ADDTNL OPTIONS, the DO key, the editing keys (FIND, SELECT, etc.), the arrow keys, the numeric keypad, PF1-PF4, and the rightmost four function keys (F17-F20). When invoking a user-defined function key string, do NOT press the CTRL key. To define a text string to be associated with a key, go to the "LC-Term Miscellaneous Menu" from the main menu, and select "Define a function key". You may only enter one line of text for each function key; the text is terminated by a carriage-return. You may put special characters in the text by using the following character sequences: Sequence Character ASCII value (decimal) -------- --------- --------------------- \t Tab 9 \n Linefeed 10 \r Return 13 \e Escape 27 \\ Backslash (\) 92 You may save function key definitions in a file, and load them from a file, with items in the "LC-Term Miscellaneous Menu". You may also save and load these definitions with script commands (see below). 7 File transfers LC-Term supports three flavors of file transfer: raw, KERMIT, and XMODEM. Raw file transfers consist of simply logging terminal output to a file, or of taking terminal input from a file. No error checking is performed. This is typically used to get a log of a terminal session, or to transfer the source program for a file transfer protocol as part of "bootstrapping" the protocol onto a machine that doesn't yet have it. - 5 - 7.1 KERMIT KERMIT is a file transfer protocol developed at Columbia University. Implementations exist for almost every computer I've ever heard of (all available at a nominal cost directly from the Columbia computing center). LC-Term currently supports a subset of the KERMIT protocol. It supports one-character checksums only (no CRCs), and server mode is not supplied. Wildcard file transmission and reception is supported. LC-Term does support repeat-count prefixing. This can considerably shorten the time it takes to transfer files with lots of repeated data bytes (executable files with lots of zeroes, or tabular text with lots of spaces). LC-Term supports 8th-bit quoting. This is disabled by default (since it reduces efficiency). You should turn it on if the path between your Rainbow and the KERMIT you're trying to talk to molests the 8th bit of characters. (You'll know this is the problem if you can transfer text files just fine but binary files never succeed.) The KERMIT menu should be self-explanatory; the only nonobvious part is that to abort a transfer in progress you press the ADDTNL OPTIONS key (which asks for confirmation before aborting the transfer). LC-Term is not yet capable of aborting a single file in a wildcard transfer; the entire request is aborted. 7.2 XMODEM XMODEM is the simplest form of the famous "Ward Christensen" protocol, named after its inventor. The XMODEM protocol supports single file transfers only (no wildcarding) and LC-Term's XMODEM implementation supports only single-character checksums: no CRCs. 8 Scripts Scripts are a powerful way of directing LC-Term to do some pretty complicated things. Scripts are very similar to raw file transmission. With one small (and powerful) exception, when you open a script file, its contents are just sent down the communications line as if you had typed them. The - 6 - powerful part is that you can embed script commands in this text which cause LC-Term to do various useful things. 8.1 Autoscripts You can invoke a script file from a menu, or on the LC-Term command line with the /s switch. You can also cause LC-Term to automatically process a script every time it's started; this is called an autoscript. If the environment variable LCTERM_AUTOSCRIPT exists (you define it with the MS-DOS SET command), its value is assumed to be the filespec for a script file which is automatically run every time LC-Term is started. Example: A>SET LCTERM_AUTOSCRIPT=C:\SCRIPTS\DIALUP.SCR A>LCTERM ... LC-Term now processes the script file automatically 8.2 Script command format Script commands begin with a sharp (#) sign. If you want a sharp sign to be sent, enter two sharp signs (##). All other characters in the file are sent as is. A script command starts with a sharp sign and is always followed by at least one character; depending on the command some of the following characters may be interpreted as part of the command. The command itself is interpreted by LC-Term and is not sent to the remote host. Case is significant: "#a" and "#A" would be two different commands. Script commands ## Send the # character to the remote system. #! Introduces a comment. All text up to and including the next newline is ignored. # A pound sign followed by a newline is ignored. This allows you to insert line breaks in a script for readability without LC-Term's transmitting the line break to the remote system. #:'label' Is a label. Labels are used as the destinations of goto commands (#g) and case statements ( #() ). Labels are not sent to - 7 - the remote system. #('response1', 'label1', 'response2', 'label2', 'nnnn') This is a case statement. It contains a comma-separated list of action pairs; each pair consists of a quoted response string and a quoted label name. If there is an odd number of entries in the list, the last entry is not a response pair, but is instead a quoted timeout value in seconds. The case statement causes LC-Term to pause in the script, examining all output from the remote system. Output from the remote system is still sent to the screen. If at any point a continuous string is seen which matches a response string, control is transferred immediately to the corresponding label in the script. If no matching response is seen within the timeout period, control drops through the case statement as though it did not exist. If no timeout value is specified, control will never drop through the case statement; the only way out is to match a string. #?'label' Specifies an error handler. If a KERMIT or XMODEM file transfer fails, control is passed to the label specified. Only KERMIT or XMODEM errors are trapped. If no error handler is specified and an error occurs, all scripts are closed and a message is displayed on the screen. #b'nn' Send BREAK for nn seconds (nn can be a floating point fraction; for example, #b'0.15') #c'command' Execute the MS-DOS command 'command'. This feature requires at least 192K. #d+ Raise DTR (Data Terminal Ready). #d- Lower DTR. #e'n' Exit from LC-Term. If a quoted string argument is present, it is parsed as an integer, which will be returned as the child process status code to DOS. This status code can be tested with the DOS batch command IF ERRORLEVEL. If LC-Term exits at the user's request (EXIT key, or EXIT menu item), and no script is in progress, it returns a status of - 8 - zero. If LC-Term exits because of an error, it returns a nonzero status code (currently it returns 1 in this case, but this may change in the future). If the user presses the EXIT key while a script is in progress, a nonzero status is returned, the assumption being that aborting a script indicates some sort of problem. #g'label' Go to the named label in the script. #i+ Make output from remote system invisible (don't put it on the screen). #i- Make output from remote system visible again. #h Hang up the phone (drops DTR for three seconds). #kb+ Place KERMIT in BINARY mode (for transmitting binary files, such as executable files.) BINARY mode is LC-Term's default. #kb- Place KERMIT in TEXT mode (for transmitting textual data). #kc'nn' Set KERMIT retry count to nn. #kg'filespec' Use KERMIT to get a file. #ks'filespec' Use KERMIT to send a file. #kt'nn' Set KERMIT timeout to nn seconds. #kx Ask the remote KERMIT server to stop itself. #k8+ Enable 8th-bit quoting #k8- Disable 8th-bit quoting #lo'filespec' Open a log file. #lc Close currently open log file. #mr'filespec' Use XMODEM to receive a file. #ms'filespec' Use XMODEM to send a file. - 9 - #p'prompt' Wait until the string 'prompt' has been sent by the remote host before proceeding in the script file. #r Reset the communications port. It's set to the parameters specified in the Rainbow's non-volatile memory (NVM); these are the parameters selected in the Rainbow's SETUP mode and saved with SHIFT-S. #s'filespec' Recursively open another script file, process it, then continue processing this script file. This allows you to create "subroutine" scripts. Scripts may be nested up to 8 deep. #t'string' Send the string to the screen. This is useful for displaying messages to the user, or for beeping the terminal bell to get the user's attention. The string may contain ANSI escape sequences. #v'name' Look up the value of the environment variable called 'name' and send its value to the remote system. You can set environment variables with the MS-DOS SET command. #w'nn' Wait nn seconds before proceeding. #x7 Ignore high-order bit of characters sent from remote system. #x8 Pass all eight bits of characters sent from remote to display. #xbr'nnn' Set receive baud rate to nnn (must be an integer, enter 134 for 134.5). #xbx'nnn' Set transmit baud rate to nnn (must be an integer, enter 134 for 134.5). #xkl'filespec' Load function key definitions from a file. #xks'filespec' Save key definitions in a file. #xp Push to a new shell. #z Closes this script, and quits terminal emulation, returning to the LC-Term main menu. - 10 - In commands that take string arguments (#ks, for instance), the first character after the command is the delimiter character; LC-Term scans until it sees a second occurrence of the delimiter and the characters scanned become the argument to the command. For instance, the following commands are all equivalent: #p'$ ', #p|$ |, #p\$ \. In commands that compare strings (#p and #(), for instance), case is significant. In commands that take durations (#b and #w, for instance), the numeric argument is expressed in seconds. Floating point representation may be used to denote fractions of seconds; #w'0.375' would cause a 375-millisecond delay. The precision of LC-Term's timers is limited by the Rainbow hardware clock to 16.7 milliseconds (20.0 milliseconds in countries with 50 Hz line current frequency). 8.3 Script usage Scripts can be quite powerful. I have a script that: - Dials a local phone number - Logs in - Connects over a DECNET network to an ARPANET host - Logs in to the ARPANET host - Runs the mail system - Copies all my new mail to a file - Leaves the mail system - Starts a KERMIT server - Uses a #kr command to transmit my mail to my Rainbow - Stops the remote KERMIT server - Logs out of both machines - Hangs up the phone I can let this script run unattended (it frequently takes 30 to 40 minutes when the network is slow) and later read my mail at my leisure, at Rainbow screen speeds. - 11 - The use of case statements ( #() ) can make scripts quite robust. The most common use of case statements is in retrying an operation until it succeeds, dialling a modem being the most typical example. Suggestion: use the #p command heavily. You need to use it when talking to systems without typeahead (like Gandalf or MICOM switches), but it's a good idea to use it even when not strictly necessary. If you use #p liberally, and something goes wrong in your script, you will probably get to a point where the script is waiting for a prompt that will never come. If you hadn't used the #p commands, the script file would blindly continue on and perhaps do some damage. #p is very patient. If something goes wrong, it'll wait for the prompt forever. You can type commands to the remote host, and perhaps fix the problem that hung the script file. Note that if you don't close the script file, it will proceed as soon as it sees the prompt it was waiting for. If you want to prevent this, use the "Raw text file transfer" menu to close the script file. 9 Poly-REGIS Poly-REGIS ordinarily does not work with LC-Term. Poly-REGIS patches itself into MS-DOS's terminal handler code; since LC-Term displays output from the remote system by calling the video firmware directly, the Poly-REGIS hook never gets called. In order to support Poly-REGIS, LC-Term is capable of passing its display output through MS-DOS. To enable this, you must define the MS-DOS environment variable LCTERM_DOS_CALLS. Use the MS-DOS SET command to do this: A>SET LCTERM_DOS_CALLS=1 (The value of LCTERM_DOS_CALLS is not significant; only its existence is.) Note that this will slow terminal output down slightly, which is the reason LC-Term does not do terminal output through MS-DOS by default. LC-Term draws its menus and file transfer display screens by writing into the Rainbow's character-mapped video memory. When Poly-ReGIS is active, the character-mapped video is disabled, and the graphics board takes over the screen. This means that LC-Term's menus and file transfer - 12 - display screens will be invisible. (They still work, so if you have them memorized, you can still use them!) This problem is hard to fix and I don't intend to fix it soon. Setting LCTERM_DOS_CALLS will fix terminal emulation, but won't cause the menus to work. Sorry. 10 Ownership, copyright, author, updates, etc. 10.1 Copyright LC-Term is copyrighted by its author, Larry Campbell. It may be copied for noncommercial purposes only. When copying LC-Term, it must not be modified, all copyright notices must remain intact, and this document must accompany the program. Commercial use of LC-Term is permitted only with my prior written permission. It is my intent that LC-Term not be used to help kill people. For this reason, I prefer that LC-Term not be made available to: any armed services, NATO, the Department of Defense, defense contractors, or the Republican Party. Of course I have no way of enforcing this restriction; I can only appeal to your conscience. Please don't encourage or assist the military. They're dangerous. 10.2 Source code For many reasons I'm not going to elaborate here, source code for LC-Term is not available. 10.3 Updates The latest version of LC-Term is usually available on a public bulletin-board system called WayStar Fido. Its telephone number is (01) 617-481-7147. If your copy of LC-Term is more than a couple of months old, it's probably worth checking here to see if a new version has been released. 10.4 Reaching the author You may reach me at the address listed on the title page. Those with access to the ARPANET may reach me by ARPANET mail as LCampbell@DEC-MARLBORO. Employees of Digital Equipment Corporation with access to the Engineering Network - 13 - may reach me at ERLANG::CAMPBELL. [End of LCTERM.MEM] - 14 - Table of Contents 1 LC-Term 1 2 Incompatible change in version 3.28 1 3 Running LC-Term 2 4 VMS KERMIT compatibility 3 5 Menus 3 6 Terminal emulation 4 7 File transfers 5 7.1 KERMIT 6 7.2 XMODEM 6 8 Scripts 6 8.1 Autoscripts 7 8.2 Script command format 7 8.3 Script usage 11 9 Poly-REGIS 12 10 Ownership, copyright, author, updates, etc. 13 10.1 Copyright 13 10.2 Source code 13 10.3 Updates 13 10.4 Reaching the author 13