
 I c e - T  XE --  Telecommunications software for the Atari 8-bit.

 by Itay Chamiel - (c)1993-2025

 Version 2.8.2 - July 13, 2025

 Email: itaych@gmail.com
 GitHub: https://github.com/itaych/Ice-T

Features:

* Highly accurate VT-102, VT-52 and ANSI-BBS emulation, including boldface,
  blink, and limited color support.
* Incredible speed for the platform - supports up to 19,200 baud, typically
  with no data loss.
* Readable 80-column text display, usable even with a color TV.
* Fully menu driven, very easy to use.
* Xmodem-CRC, Xmodem-1K, Ymodem-batch, Ymodem-G, Zmodem download protocols.
* Xmodem upload, ASCII upload, 16K capture buffer.
* 16K scrollback buffer.
* Macro support, with up to 12 macros of 64 characters each.
* Auto-dialer, with a directory of up to 20 entries.
* Built-in text file viewer and an animation file viewer.
* Fine scroll.
* Print screen and screen dump to file.

48K USERS - There is an older, less capable version supporting all machines
with less than 128K, including the 800. It is included with this release but
keep in mind that it is rather limited in its capabilities, and I ceased its
development when I started working on the 128K version.

New for version 2.8.2:
----------------------
In Ascii mode, assume 8-bit characters are UTF-8 encoded and display a square-
shaped placeholder for Unicode characters.
Fixed a couple of broken box drawing characters.
Minor bugfixes, cleanups, and performance improvements.

New for version 2.8.1:
----------------------
Added a selection of keyclick sounds and increased the keyboard repeat rate.
Removed "Rush" flow control. It was never really useful or effective.
Fixed crash that happened if data was received during the title screen.
Dialer: shortened the delay after connecting.
Fixed CSI sequence number parser to accept values up to 255, since at least
one BBS uses it during connection to detect the screen size.

New for version 2.8.0:
----------------------
Improved emulation: VT-100 is upgraded to VT-102, added VT-52 and partial ANSI-
BBS support.
Added limited ANSI colored text support, implemented using Player/Missile
graphics.
Added Macros.
For emulator users: if the D: device is absent, H: is set as the default path,
allowing you to save configuration and perform file operations without DOS.
Added Xmodem upload, albeit in its barest form (128-byte packets).
Added VT-parse file to display animations.
Improved SpartaDOS compatibility.
Support Axlon memory boards.
New "Settings" > "Return sends" menu chooses what code is transmitted when the
user presses Return.
Added many private control codes that enable BBSs to take advantage of Ice-T's
specific graphic capabilities. Added an animation file to demonstrate them.

Donation request
----------------
This software is free. However, donations are always appreciated and are a
great way to show you enjoy using my software. You can donate via Paypal to my
email address given above.

Distribute this software widely and freely!

Files in this disk image
------------------------
DOS.SYS, DUP.SYS - MyDOS system files.
HYPERE.ARR   - An E: Accelerator by Doug Wokoun, this makes the MyDOS menu run
  more smoothly.
COL80.COM    - An 80-column text file viewer.
ICET.TXT     - Ice-T user's guide (you are here).
VT102.TXT    - A technical reference of control codes accepted by the Ice-T
  terminal emulation.
ICET.COM     - The Ice-T executable.
ICETAXLN.COM - Ice-T for computers upgraded with the Axlon Memory Board.
ICET48K.COM  - Ice-T version 1.1 for 48K computers.
ICETDEMO.VT  - A demonstration animation, viewable with "VT-parse file".
*.HND - Various R: handlers. See below ("Getting started") for details.

Introduction
------------
In 1992 I began using dial-up Unix shells and discovered that the terminal
emulation programs available for the Atari were somewhat lacking, especially
in the speed department - applications like Kermit-65 and Omnicom, while doing
a fair job of rendering a VT-100-like display, were very slow and unable to
keep up with even a 2400 bps modem. Thinking about it I realized that the
major bottleneck was the 80-column display, which needed to be rendered
graphically. Especially surprising was that these programs failed to take
advantage of ANTIC's display capabilities, and actually performed extremely
slow memory-move operations in order to scroll the screen, rather than
manipulate the display list. I started with a text file reader named Col80 as
a proof of concept, and being happy with the result I started work on a
terminal emulator, which was briefly named MegaTerm but soon renamed to Ice-T
(IC are my initials; T is for Terminal), a project that took up most of my
spare time for the next 5 years.

Initially I wrote the code with the T:Edit text editor (by Bryan Schappel,
ANALOG Computing magazine, May 1987) and assembled it with A65 by Charles
Marslett. However when John Harris released the MAE integrated assembler and
editor around 1996 I quickly made the switch, and even joined efforts with him
to add 80-column as well as 64-column text modes for the editor. The greatest
advantage other than assembly speed and streamlined workflow was that the
assembler supported automatic local labels which eliminated the need to invent
a new and unique name for every minor loop and branch point in the project.

In 1997 the project was pretty much done; the program had established itself
among the standard telecommunications packages for the platform, people seemed
happy with it (several even paying the shareware fee), and for personal
reasons my spare time grew scarce. I considered 2.72 to be the final release.

Over time, however, I began hearing occasional complaints, mostly about a
certain bug where an unending stream of 'j' characters would fill the screen.
I could never reproduce this with my hardware, and when emulation software
began to add the serial port as an option, I did occasionally see the bug but
since I could hardly get the program to otherwise communicate at all under the
emulated platform, I did not get around to trying to fix it.

In April 2005 I decided to bring the source code out of the old Atari disk
images and convert them to files that could be edited and assembled on a
modern machine. It was difficult to find a cross-assembler that supported MAE-
style local labels; after some research I came across the ATasm assembler which
seemed very close to what I needed, and its author, Mark Schmelzenbach was kind
enough to add a build option "-mae" that did the trick. With that I was able to
build an executable bitwise-identical to the last 1997 release, and ATasm
remained my assembler of choice for further development.

In October 2007, addressing fresh complaints about the aforementioned bug on
the Atariage forums, I cleaned up and released the source code to the forum in
the hope that someone might look into fixing the bug, but nothing seemed to
come of it.

In April 2012, however, I happened to browse the "Program-specific issues"
section of the Altirra emulator help file and found a pleasant surprise:

   "Ice-T XE 2.72 - The keyboard click feature of this program has a bug: it
    calls directly into the OS K: handler's GET BYTE routine without going
    through CIO and without setting ICAX1Z. This causes the program to
    sometimes jam up endlessly transmitting the "j" character. Disabling the
    keyboard click and then waiting for the output buffer to drain fixes the
    problem."

With this information I decided that 15 years was enough and that it was time
to fix this old problem, along with a few other minor annoyances, and release
a new version; 2.73 was the result, and thanks to renewed interest on the
AtariAge forums I released additional versions during 2012-2013. While I was
working on the last release of this period, 2.76, I received a suggestion from
my old friend and fellow Atarian Bill Kendrick to try and implement ANSI colors
using the Player/Missle "underlay" that was already in place for boldface
characters. It took me one late night session to implement it, but there were
many little inconsistencies in how it worked, so I only released it as an alpha
version. This naturally heightened users' interest, leading to a series of
additional alpha versions with more improvements, but since I never felt that
it was quite ready there was no official release. Real life began to affect my
spare time once more, and a new and demanding job meant that I didn't have
enough time and energy to devote to the increasingly complex project. Thus
version 2.8.0-alpha7 from October 2014 remained the current version for over a
decade.

In April of 2025 I finally found the time, grabbed the old todo list and got to
work. Since I was now familiar with Git, I created a GitHub repo and committed
my entire source code snapshot history. I then fixed many lingering bugs and
finally brought the color emulation to something that I guess is about as close
as possible to a proper ANSI-BBS emulator; I also added some "private" control
codes that allow things like direct control of the underlay colors, scrolling
of the colors, painting within the overlay, and - just for fun - full Player/
Missile control and joystick and paddle input. A creative BBS developer could
write online door games with some interesting graphics, but of course they will
only work with Ice-T. This led to the long belated release of 2.8.0, followed
by a few additional minor releases.

I am always happy to hear from people using my software; I remain active as
'itaych' on AtariAge and my email address will hopefully remain valid for the
forseeable future.

Getting started
---------------
As with all software that communicates over the serial port, you need some kind
of R: handler to enable the software to communicate with your particular modem/
interface. Some interfaces already have such a handler built in, and don't need
any software to install them. The 850, P:R: connection, and anything else that
hooks up through the SIO or joystick ports, definitely need such a file.

Included with this disk image are a number of such handlers. ATARI850.HND is
for the 850 interface. The rest of the .HND files were taken from the Bobterm
archive, and are included for your convenience - I credit Bob Puff for
collecting these.

For MyDOS users, Ice-T is capable of loading the R: handler automatically if it
is needed, and even automatically unloading it at program exit. Rename the
appropriate file to RS232.COM and make sure it is located in the 'current' path
(D:) when Ice-T is loading.

SpartaDOS users are advised to create a batch file that will load the R:
handler, then load Ice-T. SDX users must use 'X' to load the application.

For other DOSes (such as Atari DOS) there is no easy solution other than to
manually load the R: handler each time, rename it to AUTORUN.SYS or prepend it
to the Ice-T executable.

If you are using APE to connect to Internet hosts, use the ATARI850.HND
handler. In APE's (R:) Internet Modem settings, make sure to select "Identify
as VT100" or "Refuse Negotiation" for best results. If you do not do this (or
are using an older version of APE that doesn't have this option) the Telnet
client may identify as a VT-52 causing incorrect control codes to be sent and
garbage to be displayed on the screen with most destinations. Also, APE may
discard LF (line feed) characters coming from the remote host, preventing the
cursor from advancing a line when it should. To fix this behavior, type ATB1
in APE's Server (AT modem simulator) mode, then connect with ATD.

If you happen to be upgrading from an old (pre-2.7) version, make sure there
is no ICET.DAT file on your disk or in the "D:" directory.
Older configuration files are not compatible with the newer software.

Make sure your interface and/or modem are ON and load ICET.COM. If your
computer has an Axlon Memory Board, you must load ICETAXLN.COM instead.

Some emulators allow loading executable files directly, without the need to
mount a disk image or boot DOS. Ice-T can work in this mode; furthermore, if
you mount a directory as a virtual disk (available as the H: device) and a D:
device is not available, Ice-T will use H: for storing its configuration file
and as the default disk path.

A brief memory and device-handler test will be performed during load time. If
you don't have 128K available, or if something is occupying the low 48K of RAM,
or if an R: handler couldn't be found or loaded, a notice will appear, and you
will be put back to DOS.

You should now be looking at the title screen. If you see the message "Can't
open port!", it means that the R: (serial port) device is not responding
properly. Try again, perhaps with a different R: handler file.

Hit any key to enter the main menu.

Before going on, I strongly recommend that you read through the rest of this
doc. Some settings in the menu (not just the baud rate!) are critical and may
cause problems if not set properly - especially slowing things down, or
causing serious data loss.

The RESET key can be used at any time to reset the terminal settings and
to get back to the title screen if you get stuck for whatever reason.

This program disables the "Attract" mode, that causes the screen colors to
change a few minutes after the last time a key was pressed, protecting the
image from "burning in". Therefore, don't leave this program on for extended
intervals without the display changing. If a wait is necessary, turn your
monitor off.

Navigating in menus
-------------------
The menu system design was inspired by the text-based user interfaces of 1990s
era MS-DOS applications such as Norton Commander, with the main menu bar at the
top of the screen and windows that drop down from the current selection casting
shadows on the background.
You may move the highlighted bar with the arrow keys (with or without holding
down Control). You make a selection with the space bar or with <Return>, and
back off into the previous menu without changing anything by pressing <Esc>.
Shift-Esc will, in most menus, instantly switch back to the terminal.
In the main-menu bar, the down arrow will work like the Return key, and open
one of the four menu windows. In these windows, left and right will switch
to one of the adjacent menus.

The main menu
-------------
This menu has five selections:
Terminal, Options, Settings, Mini-DOS, Transfer.
Seleting 'Terminal' will switch to the terminal. The other menus are detailed
below.

Options menu
------------
This menu allows you to configure some cosmetic settings to your liking, as
well as dialing and setting the clock shown on the upper right corner.

Dialing: This allows you to use the auto-dialer. In this screen, use the up and
down arrow keys to select a number to dial, then Return to dial it, or Space to
repeatedly dial until a connection is established.

E - Edit the currently highlighted entry.
A - Add a new entry, either at the highlighter's location, or at the bottom of
the list.
R - Remove this entry.

The dialing string is ATD, and then whatever you entered as the number. If you
just enter a number, it will be dialed either in pulse or tone mode depending
on your modem's default. If this is not the mode you require, you can either
change the modem's default (consult the modem's documentation to learn how),
or simply prefix your numbers with 'T' for tone or 'P' for pulse.

If you are running Ice-T on an Atari800 derivative or Altirra emulator you may
use the syntax 'I hostname port' to connect to a remote Internet host. For
example, adding an entry with the following text instead of a number will
enable a telnet connection to www.atarinews.org:

     I www.atarinews.org 23

Note that 'I' is case sensitive; also, as is the case with a real modem, the
Hangup feature may be used to end the session. Note that as of this writing,
Atari800 indicates a successful connection with 'OK' instead of 'CONNECT' and
is therefore incompatible with this dialer.

After getting connected, the status bar will indicate "Online", and a timer
indicating online time. Your hosts's name is also shown.

Macros: Ice-T allows defining up to 12 macros of up to 64 characters each. The
submenu that opens shows the available slots; each slot may be empty, indicated
by a dash sign, or taken, showing the letter or number to which that macro is
assigned. Select any entry to create or edit the respective macro.
The next window that appears will let you assign a key to this macro, or change
the key already assigned. Press Ctrl-X to remove this macro, or press any
alphabetical or numeric key to select the assignment. The macro will be invoked
in the Terminal by holding down START and pressing that key. Press Return to
proceed.
You will now be presented with a window for entering or editing the macro text.
If you need to output something other than plain text, you may generate special
characters as follows:
- To insert a control code, the percent symbol '%' can be used. The character
immediately after '%' will be sent stripped of its upper 3 bits, so %X or %x
will send Ctrl-X (ASCII code 24) and %[ will send Esc (ASCII code 27). To send
the percent sign use '%%'.
- To insert an arbitrary byte use '$' followed by 2 case-insensitive hex
digits. To send the dollar sign use '$$'.
As a useful example, the following sequence will send an Xterm style "page
down" key code: %[[6$7E
Instead of the 6 you can place any digit from 1 to 6 for Home, Insert, Delete,
End, Page Up and Page Down, respectively.

Keyclick: Choose between five different pitches for the keyboard click, or no
click at all. The one named Standard sounds the same as the standard Atari OS
built-in click, though it is slightly shorter.

Special: Select one of the special display modes. "None" is for none at all.

* ANSI colors - enables a full color display, supporting ANSI-BBS/Xterm style
colors to the extent possible within the Atari's hardware limitations. Coloring
the text is achieved with a Player/Missile "underlay"; The four players and
four missiles (grouped into a fifth player) are quadrupled in horizontal size
and spread across the screen. Since each player is 8 pixels wide we have a
total of only 40 pixels, which means that coloring a single character will also
affect its neighbor. Also, five players means that we only have five colors
available across each line of the screen, each affecting a block 16 characters
wide. If an attempt is made to use two different colors within the same region
the most recently applied color will change the others within that range, often
causing unwanted effects. Vertically there is no limitation thanks to a Display
List Interrupt routine that updates the colors for each line.
An additional limitation is that ANSI allows speciying the background and
foreground text colors separately, but only one color may be displayed; if both
are specified then the background color takes priority.
The additional CPU and memory accesses caused by the DLIs and Player/Missile
DMA do cause a minor performance hit, therefore an effort has been made to
disable them when no colored or bold characters are present.

* Bold text - this uses the same PM underlay as ANSI color mode but is limited
to only displaying bold (bright) text.

* Blinking text - enables support for blinking characters, using the same PM
underlay. In this mode colors and bold are not supported.

* Fine Scrolling - enables smooth scrolling of the text in the terminal and
file viewer. This scroll is done in VBI (a background process), which means
that new data continues to be displayed while the scroll is taking place. This
is useful when reading a lot of scrolling text on a slow connection, but can
slow you down excessively in other cases. I recommend trying it.

Background: You can select the background hue and whether the text is light on
a dark background or vice versa. Monochrome monitor users should only use
color 0, and choose inverse mode according to their
preference. Color monitor users should choose the setting which renders the
80-column screen most readable. I recommend trying 1, 2, and F, in both
inverse and standard modes.

8-bit set: This defines how the terminal handles values with the high bit set,
referred to here as "8-bit" values.

* Ascii - this setting is recommended for Unix/Linux shells and any other host
that expects a classical VT-100 terminal. 8-bit values, if present, are assumed
to be UTF-8 encoded Unicode characters; however since Unicode is not supported
a simple square icon will be displayed where you'd expect an extended character
or an emoji. Note that the UTF-8 parsing is rather naive, so an invalid stream
of bytes may create more of these squares than would appear on a fully
compliant decoder.

* IBM-PC - this enables the IBM PC "Code page 437" character set, commonly used
by PC-based BBS systems for displaying character art and graphical menus. This
is therefore recommended for BBSs, in conjunction with the "ANSI-BBS" emulation
setting.

Note that in this mode any UTF-8 characters will appear as a string of garbage.
These are typically not used by BBSs so this should not be a concern.

Due to system limitations, the scrollback/screen redraw buffer will lose the
inverse attribute of characters in this mode.

Cursor style: Choose between an underline cursor or a block one.

Set clock: Sets the clock in the upper-right corner of the menu screen.
The current time will be displayed (upon startup it is set according to the
R-Time 8 clock if available, otherwise 12:00).
Use the arrows and number keys to change the setting.
For example, if the time is 10:48 you just type "1048" and you're done.
If it says 10:47, you press "->" 3 times (or "<-" once) and type 8.
The clock cycles at 12:59 to 1:00. There is no AM/PM display.
Pressing Return will set the time. Note that the R-Time 8 internal clock is
not updated with the new time.

Zero timer: This will reset the terminal's online timer.

Reset term - Reset all the internal VT "registers". This should be used if
badly-written software at your host, noise in the line, or a sudden hangup
leaves the terminal in a wrong mode. For example, if graphics mode is enabled
when text is received, or if scrolling seems to stop working because the
scrolling lower boundary is above the cursor's location.

Settings menu
-------------
This menu is for setting your hardware for proper communications, with your
modem and remote host.

Baud rate: Sets the serial port communications speed. 14.4kbaud users should
select 19.2k. Also, 850 users should note that this interface doesn't support
19.2k, so that option would have the same effect as 9600. Emulators may
throttle the data rate according to this setting, so set it to the maximum.

Local Echo: When on, every character you type in Terminal will be sent to
your host, but also sent directly to the VT100 processor, echoing what
you typed. This option should be used with systems that don't automatically
echo what you type back to you. The recommended setting is 'off'.

Stop bits: Normally set to 1.

Auto-wrap: Determines whether the cursor will wrap-around to the next line
when it reaches the edge of the screen. Note that when entering this menu,
the highlighted bar will NOT indicate the present status (which may be
changed by a code from your host), but it shows the default mode, present
when you load the program or reset the terminal (by pressing <Reset> or
by selecting that option).
Changing this setting WILL alter the current state, though (leaving this
menu by hitting Esc will not).

Emulation: Choose VT-102, ANSI-BBS, or VT-52. BBS users should use the
corresponding option. The differences between VT-102 and ANSI-BBS are subtle;
some BBS art will be affected by it, as would certain pedantic applications
such as Emacs. The vt102.txt document details the differences.

Always be sure to use a setting that corresponds to what the host expects. On a
Linux/Unix host set the environment variable TERM to "vt100" or "vt102" for
VT-102, "vt52" for VT-52 or "ansi" for ANSI-BBS. If you're using a Telnet
client to connect, ensure that it identifies as one of these strings if you
want this to happen automatically.

Return sends: Normally pressing Return will transmit a CR, unless the remote
host sends a control code named Set Insert mode after which Return will
transmit CR+LF. You may override this behavior to send a CR, a LF, or an
ATASCII End of line.

Delete sends: Normally a VT-100 terminal will transmit a DEL ($7F) when the
user presses the backspace key. The two additional options are BS ($08,
equivalent to Ctrl-H) or Backsp, which means the ATASCII delete ($7E).
Note that Shift-Backspace will transmit an alternate code as follows: If you
selected DEL in this menu it will transmit BS and vice versa; if you selected
ATASCII it will send DEL.

End of line: Choose which incoming character is interpreted as an EOL.
This shouldn't be confused with a similar menu in the Mini-DOS menu, which
handles EOL conversion during file transfers and capture only.
CR + LF  - Normal. CR moves cursor to the left edge and LF does a line feed.
LF alone - LF is treated as a CR+LF sequence. CR behaves as normal.
CR alone - CR is treated as a CR+LF sequence. LF behaves as normal.
ATASCII  - 155 ($9B), the Atari "Return", is recognized as an EOL. Also,
           the Atari TAB ($7F) character is recognized. Note that CR or LF
           are still recognized in this mode and behave as normal.

Status calls: This setting is fairly crucial for proper operation of this
software. Basically, if you're using anything faster than 4800 baud, use
"Constant". This setting determines how often the R: input buffer is polled and
emptied into Ice-T's larger 16K buffer (indicated by the Bf: indicator), when
Ice-T is already busy rendering the contents of this large buffer to the
screen. The issue is that most interfaces (not the 850) have a very small (128-
byte) input buffer, which easily overflows if not emptied often enough. On the
other hand, some interfaces allow using a larger input buffer, and therefore
there is no need to waste time on polling them too often. Experiment with the
settings until you find the best for your setup.
Just to get the numbers straight:
The 850, and any interface fully compatible with it, will use a 256 byte input
buffer allocated by Ice-T. Other devices seem to ignore CIO requests for larger
buffers, and use a 128 byte buffer. The amount of characters processed in
between polling the R: buffer is:
Normal   - 1024 bytes
Medium   - 16 bytes
Constant - 1 byte.

Flow control: Choose between None or XON/XOFF.

Ice-T has a 16 KB cyclic buffer for incoming data. If flow control is enabled
it will take effect when 12 KB of the buffer are full.

This can happen if:

* The buffer gets that full during Pause mode (data keeps flowing in);
* When fine scrolling, or heavy use of ANSI codes cause Ice-T to slow down and
gradually accumulate characters (rare at low speeds);
* Too much high-speed data (9600 and up) arrives at once, and is simply too
much for the software to handle, in which case the buffer will gradually
fill up.

If the buffer gets completely full (16K), Ice-T will stop GETting data from the
serial port, whether flow control is enabled or not. This will implicitly
activate hardware flow control if your hardware happens to support it. If it
does not, further incoming data will be lost.

When XOFF is in effect, a small brick character will appear at the upper left
corner of the screen. Ice-T is smart enough to transmit additional XOFF codes
if data continues being received, but it will not do so more than once per
second.

Save config:
This will save the current settings, autodial entries, and macros into
D:ICET.DAT, or H: if the D: device is not available. Note that the path setting
in the Mini-DOS menu has no effect on where this file is saved.

See the file icet_cfg.h (from the distribution zip file or Ice-T's GitHub
repository) for a description of the file format, contents, and valid values.

Mini-DOS menu
-------------
Disk directory:
This will display the directory of the path specified in "Change path".
Hit any key to return to the menu.

Change path:
Select the general pathname for all disk operations.
Ice-T will try to complete incomplete names. If what you entered doesn't
begin with a "D", a "D" will be added. If it doesn't end with a ":" or with
a ">", a ":" will be added. This means that "2" will be translated to "D2:".
":icet" will be translated to "d:icet:".
Also note that all names are displayed and entered in lower case.

D/L EOL trans.: Download EOL translation, for capture and protocol transfers.
None - File transferred as-is. Good for binary transfers.
 CR  - CR turns into an ATASCII EOL, LF is dropped. This is recommended for
       most common (Unix or Windows) text formats, since CR/LF pairs are
       translated properly.
 LF  - LF -> EOL, CR dropped.
Either - Either code is translated to EOL. Don't use this if CR/LF is
used in the original file, since you'll end up with two EOLs between each
line.

U/L EOL trans.: Upload EOL translation for ASCII upload and Xmodem upload.
EOL -> CR/LF - EOL translated to the CR/LF pair.
EOL -> CR    - EOL translated to CR.
EOL -> LF    - EOL translated to LF.
No change    - File uploaded as-is. Use for binary transfers.

Capture ANSI: Allows stripping of all ANSI codes from captured data.
This has no effect on protocol transfers (X/Y/Zmodem).

View file: Read contents of a file. Press the space bar to advance by one page,
or Return for one line.

VT-parse file: This loads a local file from disk and sends its contents to the
Terminal, as if they had been received from the remote side. This is useful
mostly as a way to view clever VT100 animations, such as the ones available at
http://artscene.textfiles.com/vt100/ . Note that some of the animations require
changing Settings > End of Line to "LF alone". A demo animation named
"icetdemo.vt" is included on the Ice-T disk, I hope you enjoy it.

The following controls are available during animation playback:
- START: freeze until released.
- SELECT: slow down (approximating a 9600 baud connection).
- OPTION: extreme slowdown (one character per vertical screen refresh).
- Any keyboard key to abort and return to the Terminal.

Rename file:
Type in the current name, then the new, with a Return after each.

Delete, Lock, Unlock:
File operations. Type in a file name and Return to apply the action.

Transfer menu
-------------
Toggle capture: Enable or disable saving all incoming data into the capture
buffer, marked by the "C:" indicator in the terminal status bar. Data will be
saved in this buffer as it is displayed in the terminal (which may occur after
it is received). All EOL translation and ANSI stripping, if desired, will occur
at that point, and not when saving; Make sure you have the proper settings for
these before receiving the data.

Save capture: This will allow you to save the current capture buffer into a
disk file, or to discard it. Note that this *appends* the buffer's contents to
the end of the currently existing file. This can be used to capture lots of
data into one file, with a save being done once in a while to make room for
more data. Any data coming in *during* the disk operation will be lost,
however, so make sure nothing does.
Once the file is saved, capturing is halted; use the "Toggle capture" menu
entry to re-enable it if desired.
Using the 'E' key to empty the buffer will also stop capturing.

ASCII upload - Send a file to the remote host, with no protocol.
You can add a delay between every line sent, or request the upload to wait for
a prompt from the remote host before sending the next line. These two are
mutually exclusive. During the upload, press 'p' to pause/unpause the sending.
Press Esc to abort. Incoming XOFF/XON characters are respected, and will cause
the transfer to pause and unpause respectively. The 'p' key can be used to
manually unpause if this causes the transfer to get stuck for some reason.

Xmodem receive - This is an implementation of Ward Christensen's original
protocol, developed in 1977. It includes all the later additions, including
CRC-16 error checking, and 1K-block capability (sometimes incorrectly
referred to as Ymodem). Each of these are used if the host supports them.
To transfer a file you must first give the suitable command to your host ('sx'
under most flavors of Unix). You may request Xmodem-1K (from the host!) if you
wish - it's faster with a clean line. Remember to set D/L EOL Trans. to "None"
before transferring a binary file. Then exit to the menus and select this
option. The Xmodem protocol doesn't exchange any file information, therefore
you have to type in the file name.
The transfer will begin, and you will be notified about most of what's going
on. Downloading will stop every incoming 16K to save to disk.
The main drawback to this protocol is that a maximum of 127 extra bytes,
or 1023 bytes in 1K mode, can get added to the end of the file.
If your sender program was written properly, it should be able to minimize this
problem in 1K mode by using 128-byte packets towards the end of the file (since
the receiver is capable of handling any combination of 128 or 1024-byte
blocks).
The contents of these bytes are usually Ctrl-Z, but again you're at the mercy
of whoever programmed your host's software. They may just contain junk.
Text files, UUencoded files and ARC files will come through safely, but if your
file can't tolerate junk at its end, use Ymodem or Zmodem.
Xmodem is always to be used as a last resort only - Ymodem is better, Zmodem
is best.

Ymodem receive - This protocol is similar to Xmodem, with a few additions:
1. Block check is CRC-16, and never checksum (fascinating, isn't it).
2. More than one file can be transferred per session, and you may use
wildcards to send more than one file (for example, you can request a file-
name like *.DOC for all files with the DOC extension to be sent).
3. The file's name is reported by the host, so you don't have to type it in.
4. The file length is also sent, so there is no file padding as in Xmodem.
(This capability is lost, however, if the file is over 16MB long; such large
files will be padded.)

This implementation complies with Omen Technologies' definition of
"True YMODEM(TM)", but I can't officially say that if it hasn't been
certified by them. I am not going to attempt this.

To transfer a file, request one or more files to be sent from your host ('sb'
under Unix) then select Ymodem receive in the Ice-T menu. The rest will be
done automatically.

Ymodem-G receive - This is a "streaming" version of Ymodem - the other side
won't pause between packets for an acknowledgment, and in case of an error
the transfer will be aborted. For this reason, this protocol should best be
used with a reliable null-modem cable, or with an error-correcting modem.
Another thing that should be noted is that this transfer may not be used if
both modem and disk drive are connected through the serial port. The transfer
will attempt writing to the disk while the modem port is still open, and
this will cause a system crash with such a hardware configuration. Even with
a RAMdisk, data may be lost because RAMdisk access disables interrupts which
may be crucial to receiving serial port data; in that case data will be lost,
causing an error and aborting the transfer.
To date, this mode of file transfer has only been verified to work under the
Altirra emulator. Please update me of success on real hardware.

There is no special command required to activate Ymodem-G on the host;
request a regular Ymodem transfer as described above, then select Ymodem-G in
the Ice-T menu.

Zmodem receive - This is the best protocol of them all. Like Ymodem-G, it uses
streaming (no pause for acknowledgement) for maximum speed. Unlike it though,
error recovery is possible. In addition, it is usable with all hardware
configurations, since the host will stop every 16K to let Ice-T write its
buffer to disk. If your host doesn't support this pause (in violation of the
standard), a "Buffer overflow!" message will appear. Ice-T will pause to empty
the buffer to disk, then resume, requesting the other side to repeat all the
data that had been lost during the disk save. This should cause nothing more
than a delay.
Unfortunately the current version of 'lrzsz' (the X/Y/Zmodem transfer utility
included with current Linux distributions) suffers from this problem.

While the protocol supports CRC-16 and CRC-32, only CRC-16 is supported by
Ice-T.

To begin a transfer, request one or more files from your host ('sz' under
Unix). This will automatically begin the download; you may never actually have
to select this option in the menu.

If a download is aborted for any reason, all validated data will be saved,
and the file will close (no junk will be saved in the file). In addition,
a file with the same name and a .RCV extension will be created, saving the
received file's length; This file will be needed for crash recovery.
When beginning a download, Zmodem will check if the filename to be transferred
already exists locally. If it does, a .RCV file will be searched for, and
the file transfer will continue from where it left off.
If this .RCV file is not found, Ice-T will assume that this is NOT a crashed
file, but it will not overwrite the old file; It will rename it by replacing
the second character of the filename with a zero. If again such a file is
found, the process repeats, increasing that number. It will cycle at 9.
In the unlikely case that Zmodem can't find an unused name, it will cycle
indefinitely; Press Esc to abort.

Xmodem send - uploads a file using the Xmodem protocol. Only 128-byte packets
are supported, and due to the protocol's limitations the transferred file will
be padded with up to 127 bytes of 0x1A. Note the setting of Mini-DOS > U/L EOL
Trans. as this will affect transferred files.

Quitting the program
--------------------
Hit <Esc> in the main menu. You will be asked whether you really wish to
quit. A positive response will terminate the program, exiting to DOS,
while saying no or pressing <Esc> will return you to the main menu.
You also have the option of removing the R: handler and freeing the memory
taken by it; this will only be possible if the handler was loaded by Ice-T (by
renaming it to RS232.COM, as described in the "Getting started" section).

The Terminal
------------
The terminal is entered by selecting "Terminal" in the main menu. In this mode,
whatever you type on the keyboard is sent to your host via the serial port, and
anything received is handled - either as a control code or as a character to be
displayed.

Pausing:
Ctrl-1 will toggle Pause mode. In Pause, all the keys work normally, and you
can continue typing. Whatever you type will be sent to the host, but anything
received from the host will be saved in the buffer, and will only be displayed
when you press Ctrl-1 again. You can also exit to the menu from within Pause.
Returning to terminal will put you back into Pause.

When in Pause mode, you can use the OPTION and SELECT console keys to scroll
the screen up and down respectively, to view the backscroll info.

A "quick-pause" mode is entered by pressing OPTION to scroll back, when in
normal terminal mode. While viewing the backscroll, any incoming data will
bring you back to the main screen. This is useful if you're waiting for
something and wish to read previous screens while waiting, knowing that you'll
see it as soon as it happens.

Print-screen (Ctrl-Shift-P):
Will print the screen, as regular text, to any printer that is accessible
through P:. Underlined or inverse text will appear normal on the printed page,
and large-sized characters will also look normal, but will be spaced apart.
ANSI graphics characters will not be printed, but characters above 128 (in PC
characters mode) will be, and are supported by most printers. Backscrolling
will not affect the printout; Only the main screen gets printed.

Screen-dump to disk (Ctrl-Shift-D):
Will dump the screen's contents to a file in the current path. The file will be
named SChhmmss.TXT, where hhmmss are the hours, minutes and secods of the
current time as displayed in the menu. In case of conflict the previous file
will be overwritten. The lines in the output file are separated by ATASCII EOL
characters.

Hang-up (Ctrl-Shift-H):
Causes the modem to hang up by waiting 1.5 seconds, sending a "+++", waiting
another 1.5 seconds, and sending an "ATH" followed by a carriage return.
The status line will indicate "Manual" (offline) mode.

Switch to menu:
Press Shift-Esc to switch to the main menu. If you are expecting data to arrive
while you will be using the menu, or even if a new page of data is still being
received, don't worry - any incoming data will be preserved, and up to 16K of
text can come in without problems. XOFF flow control will remain active in the
menus. Be warned, however, that any disk operation necessarily means closing
the R: port, and data received during one will be lost.

Using the keyboard in Terminal:
Every usable key sounds a click when pressed (if click is enabled), so you'll
know whether what you just pressed actually did something.

Pressing a key with START held down is like Meta-[key], which means it sends
an Escape before that key. For example, START-x will send a Meta-x, or
"Esc x". This has no effect with keys that send more than one byte, like the
arrow keys.
If you have assigned some key to a macro, press START and that key to transmit
the macro contents. This will override the Meta-[key] behavior.

Pressing anything with SELECT held down will send that code with the
high bit set. Like START-key, it only works with the "simple" keys. I doubt
it'll ever need to be used, but when offline you can test the PC character
set (make sure it's enabled in the "8-bit set" setting).

Here is a list of legal keys:

^ means the Control key.

Local-function keys:
Shift-Esc      Exit to menu
^1             Pause (indicated in status line)
Break or ^Esc  Send 0.23 second break signal (or 3.5 seconds with Shift key)
Caps           Toggle Caps lock (indicated in status line)
Shift-Caps     Set caps lock to on
^Shift-P       Print screen
^Shift-D       Dump screen to file
^Shift-H       Hang up

VT-100 Numeric keypad emulation is invoked by the following keys with ^Shift:
  0-9     -  Numeric-keypad 0-9
  Comma, period, minus, <Return> - Numeric keypad equivalents
  Q,W,E,R - PF1,2,3,4 respectively
(Note that the codes transmitted by these keys depend on the Num-lock setting,
which is indicated by an 'N' in the status line and is controlled by a code
sent from the host.)

General keys:
A-Z       - Lower or upper case according to Caps setting.
Shift-A-Z - upper-case if Caps is off, lower-case if on.
^A-Z, 0-9, Shift-0-9, Esc, Tab, <Return>, others not mentioned - as expected
<Delete>  - Delete code specified in the "Delete sends" menu
Shift-<Delete>  - Alternate delete code, see the "Delete sends" description.
Ctrl-arrow keys - up, down, left, right. Code sent depends on cursor-key mode
                  (controlled by host).
(1200-XL only) Function keys: same as Ctrl-arrow keys - F1,2,3,4 are up, down,
                  left, right, respectively.
^7 - Accent mark
^9,0 - Curly brackets
Inverse/Atari logo key - tilde

Special-purpose ASCII characters:
^comma       - ^[ ($1B, same as Esc)
^period      - ^] ($1D)
^6           - ^^ ($1E)
^8 or ^space - ^@ (null)
^colon       - ^_ ($1F)
^?           - ^? ($7F, DEL)

Further reading
---------------
The following additional documentation is available:
quickstart.txt - contains instructions to quickly configure an emulator for
  running Ice-T.
vt102.txt - this is a reference of all control codes accepted by the Ice-T
  terminal emulation; an in-depth documentation of the graphical abilities and
  limitations unique to Ice-T; and the extended "private" control codes.
icet_cfg.h - this is a description of Ice-T's configuration file format.

Acknowledgments
---------------
I'd like to thank the following people for their contributions:

Jeff McWilliams, for lending a hand in upgrading my stock 130XE to the
powerful machine used in development.
Clay Halliwell, for direct competition in the form of FlickerTerm80, as well
as giving me several ideas (such as bold/blink support) and help with various
optimizations.
Bill Kendrick, for testing, ideas, bug reports, and moral support.
John Harris, author of the MAE assembler/editor used for the majority of
development up to version 2.72.
Russ Gilbert, for help with the CRC error checking and beta testing across a
wide variety of hardware configurations.
Tom Drake, for help and feedback.
Mark Schmelzenbach, for the ATasm assembler, and adding the -mae option at my
request; and to Peter Hinz for further ATasm updates and bugfixes.
Avery Lee (of Virtualdub and Altirra fame), for solving a 15 year old bug and
motivating me to release a fix.
Steven Tucker, author of APE, for the excellent R: proxy, allowing the Atari
running Ice-T to act as a Telnet client.

Enjoy Ice-T!

Itay Chamiel
Jerusalem, Israel
---------------
