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<filespec> 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.
#<newline> 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