I c e - T XE -- Telecommunications software for the Atari 8-bit. by Itay Chamiel - (c)1993-2013 Version 2.76 - October 10, 2013 Email: itaych@gmail.com Features: * Complete VT-100 and ANSI-BBS emulation, including boldface/blink support. * Takes advantage of XE/upgraded-XL banked RAM to provide many features. * Incredible speed - supports up to 19,200 baud, with no data loss! * Readable 80-columns, usable even with color TV. * Fully menu driven, very easy to use. * Xmodem-CRC, Xmodem-1K, Ymodem-batch, Ymodem-G, Zmodem download protocols. * ASCII upload, 16K capture buffer * 16K scrollback buffer * Auto-dialer, with a directory of up to 20 entries * Built in text 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 should be available at your favorite Atari software archive (sometimes incorrectly offered as a "64K" version). That version has a number of bugs, and I abandoned it when I moved on to a new version for the more capable 128K machines. Version history: 2.76 - October 10, 2013 ---- SpartaDOS: TDLINE is now disabled automatically in nearly all versions (2.x, 3.x, SDX 4.4 and above). Fixed some cases where CPU intensive events such as clearing the screen could cause data loss. VT100: Many improvements to emulation with the goal of conforming to the VT100 specification as closely as possible; now passes all tests in the 'vttest' suite relevant to VT100 emulators. - Added Origin mode, LEDs, DECREQTPARM (request terminal parameters) command. - Answerback string changed to "Ice-T". - Shift-Break now sends longer break signal, as per the VT100 spec. - Various misbehaviors, bugs and glitches fixed. 2.75 - October 1, 2013 ---- Fixed a major regression from version 2.73 which broke compatibility with the P:R:Connection, MIO, and possibly other interfaces, due to incorrect reset of the BREAK key status. Thanks to Russ Gilbert for reporting and assistance in solving the bug. VT100: Fixed some visual errors when changing the width of existing text. Title screen: Fixed minor visual glitch if serial port failed to open. 2.74 - September 25, 2013 ---- Minor speed improvement in text rendering thanks to Jon Halliday (author of The Last Word). Screen dump to disk added. R-Time 8 cartridge support was buggy, fixed. Minor improvement to clock accuracy (when no RT8 present). RS232.COM automatic loading is now only attempted under MyDOS. SpartaDOS 3.x: Added automatic disable for TDLINE if it is on. (SDX users, sorry but I couldn't get this to work.) SpartaDOS 3.x: The configuration file ICET.DAT will now be correctly loaded from the current path. Also the default current path in the Mini-DOS will also point to the current path. SpartaDOS X: Ice-T must be loaded with the 'X' command. A reminder is shown if you did not. Mini-DOS: Path will now accept any single-letter (or letter and number) device type, so you can use files on things like H:. Also '\' is now allowed as a directory separator. File Viewer: Fixed EOL parser, should work with Unix/Windows/ATASCII files. VT100 emulator: Minor tweaks to font; Underline now ignored for mode 3 (top half of double height row) text; Fixed the bug discovered at the release of 2.72 (see below) involving scrolling portions of the screen in boldface mode; Fixed bug that caused double-width/height lines to misbehave when scrolling upwards. Bold text is now enabled by default. With these fixes the VT100 'torture test' now passes. 2.73 - April 14, 2012 ---- A bug in the way I called the OS keyboard handler in order to generate keyclicks caused an endless stream of 'j' characters to appear when "standard" keyclick was enabled, under certain circumstances. Thanks to Avery Lee (aka phaeron, author of the Altirra emulator) for pinpointing the cause of this bug. R-Time 8 cartridge supported for clock that is displayed in the menu. Even without R-Time 8, clock and timer are now far more accurate, particularly on PAL machines. The 'break' key may now be used (in addition to ^Esc) to send a break. Arrow keys in the menus may now be used with or without holding down Ctrl. Some fixes made to way I access the serial port device (R:). Dial string changed from ATDT to ATD. Fixed timing bug in dialer. Dialer will now hang up before dialing, if you were already online. Fixed potential crash when quitting the program. Removed registration nag messages. 2.72 - February 12, 1997 ---- Print screen didn't work.. Pretty stupid mistake I made, I admit. Dialing string changed to invoke tone dialing only. See the "Dialing" section for details on how to use pulse. Discovered a minor annoying bug involving scrolling *portions* of the screen in boldface mode. It seems to strike especially when using IRC (through a dialup Unix/VAX shell) in multi-window mode.. My favorite online activity!! Grrr... I don't have time to fix this. Minor cosmetic bug in XON/XOFF flow control - ditto. 2.71 ---- Bug fixes involving directory listings, screen clearing with 40-column (wide- character) lines on the screen, and setting scrolling margins. These are, I admit, pretty minor. I didn't have any free time! Major additions for 2.7 ----------------------- Zmodem download - including crash recovery (resume a download later in case one was aborted in the middle). CRC error cheking now done using tables - no more speed limits for transfers! Tables are calculated, as opposed to being loaded from disk. Added boldfaced (highlighted) and blinking characters. Only one of these features may be active at one time, though. Menu controls enhanced - the windows are more PC-like. Left/right will switch between different menus now. R: handler now loaded automatically. No more appending. Fixed disk-directory to allow for more than one screen to appear. (SpartaDOS doesn't limit the number of files allowed in a directory.) Some support added for those with automatic hardware flow control (Black-Box, MIO): Stops GETting data from R: if my buffer is full. Reset-terminal function and VT100 code added. Fixed a bug involving overwriting underlined spaces. Reset key now works properly, even if used more than once. Various other bug fixes, as usual. "Attract mode" now truly disabled. 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 - E: Accelerator by Doug Wokoun README.TXT - An ATASCII-format introductory text file. ICET.COM - The Ice-T executable. ICET.TXT - This document. VT100.TXT - Documentation of the VT-100 terminal, as implemented in Ice-T. *.HND - Various R: handlers. See below ("Getting started") for details. COL80.COM - An 80-column file reader, which you may use to read this document. 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. 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; I chose ATasm as the assembler and (thanks to its author, who added a special build option at my request) managed to get it to create an executable bitwise-identical to the 1997 release. 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, with subsequent versions being mostly bug fixes or minor feature additions. Future development will depend on the level of interest of the users. Thanks to accurate emulators with advanced debugging capabilities, fast cross- assemblers running on modern hardware and the availability of all relevant documentation online, it is now easier than ever before to develop for the Atari 8-bit. Unfortunately, there are very few users still using Ice-T and so at this point I doubt there will be any further significant development. I am always happy to hear from people using my software; my email address will hopefully remain correct for the forseeable future. Getting started --------------- As with all programs that talk to a modem, 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 needs such a file. Included with this disk 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. 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 program. For other DOSes (such as Atari DOS) there is no easy solution other than to load the R: handler manually 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 will 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. A brief memory and device-handler test will be performed during load time. If you don't have 128K free, 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. Loading time will be considerably shorter than normal if you had already loaded in Ice-T before. Your scrollback buffer will be preserved if you had used "Quit" to terminate the program (as opposed to a coldstart or power cycle). 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. Note that in this document the prefix '^' may be used instead of "Control". Navigating in menus ------------------- The menu system design was inspired by the user interfaces of 1990s era PC-DOS plain text applications such as Norton Commander, with the main menu bar on 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 , and back off into the previous menu without changing anything by pressing . Shift-Esc will, in most menus, bring you 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. After getting connected, the status bar will indicate "Online", and a timer indicating online time. Your hosts's name is also shown. Keyclick: Choose between the standard Atari built-in click, the simple quiet 'tick' sound, or no click at all. Special: Select one of the special display modes. "None" is for none at all. * Bold text - enables displaying bold (bright) text. This uses a player/missile "underlay" to highlight characters. The four players and the 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 40 pixels, which means that a normal character adjacent to a bold character may be incorrectly displayed as bold. However in most cases boldfaced words are separated from normal words by at least one space, so this should usually have no visible effect. Since player/missile graphics require additional DMA time for ANTIC, this will cause a minor performance hit, however effort has been made to disable this DMA when no bold characters are actually visible on the screen. * Blinking text - enables support for blinking characters. This is internally identical to bold, except that the PMs are black (obscuring the blinking characters), and alternate on/off every half second. A real VT-100 terminal is able to display both bold and blinking characters, but due to the Atari's limitations only one or the other is possible at a time. * 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 is useful for PC-based BBS systems, which heavily use characters above 127 for character graphics and menus. However, if you select this, the scrollback buffer will not preserve inverse characters as such. Since this is not a part of the ANSI standard, you may wish to leave this off when using most Unix/VMS dialups and Internet access systems, since they will probably use the ANSI graphics mode, which doesn't need 8-bit characters. Cursor style: Choose between an underline cursor or a block one. Set clock: Set 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 set the terminal's online timer to zero. 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: Set the communications speed between your computer and your modem. 14.4kbaud users should select 19.2k. Also, 850 users should note that this interface doesn't support 19.2k, so selecting it is the same as choosing 9600. Emulators will 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, and 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 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-100 or ANSI-BBS. I only know of one difference between these two (ANSI homes the cursor when clearing the screen, VT-100 does not). Delete key: Some hosts will only recognize $7F as delete, and others will need ^H. Choose the one suitable for yours, or the one used most often. 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 and LF does a line feed. CR or LF - Either CR or LF are treated as a combination of both. ATASCII - 155 ($9B), the Atari "return", is recognized as an EOL. Also, the Atari TAB character is used. (CR or LF are still usable.) Status calls: This setting is fairly crucial for proper operation of this software. Basically, if you're using anything faster than 4800, use "Constant". 850 users should use "Normal". This setting determines how often the R: input buffer is emptied into Ice-T's large 16K buffer (indicated by the Bf: indicator), when Ice-T is already busy emptying 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 loses data if not emptied often enough. On the other hand, the 850 allows using a large input buffer, and therefore there is no need to waste time on calling Status 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 2K input buffer. Many other devices ignore CIO requests for larger buffers, and use 128 bytes. The amount of characters processed in between emptying the R: buffer is: Normal - 1024 bytes Medium - 16 bytes Constant - 1 byte. If the 16K buffer is empty, status calls are done constantly in all cases. Flow control: Choose between XON/XOFF, Rush, neither or both. Ice-T has a 16 KB cyclic buffer for all incoming data. Both of these flow-control schemes kick in 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 full (16K), Ice-T will stop GETting data from the port. This will enable automatic hardware flow control, for those interfaces which support it. You may disable all flow controls by selecting "None", and this will still happen. Any form of flow control will actually occur quite rarely; At 9600 baud, about 37 KB of data have to come in, non-stop, for the flow control schemes to kick in; At 19.2kbaud, 16 KB of data has to come in. Even if no flow control is enabled, much more that that has to arrive before any overflow (and therefore data loss, if your interface doesn't support auto hardware flow control) occurs. Incoming data keeps getting buffered up even if you're in the menus. XOFF remains enabled, but Rush does not, meaning that if you select Rush only, no flow control will be active and the buffer may overflow. When XOFF is working, a small brick character will appear at the upper left corner of the screen. Ice-T is smart enough to send more Ctrl-S characters if the first one was ignored, or if the remote host snaps back to life after a few moments of silence. In no case, though, will more than one ^S code be sent per second. As for the "Rush" flow control, I'm pretty sure it's never been done before (with good reason, too, I guess), so here's a quick description: Instead of "Online", "Paused", or "Manual" in the upper left corner, "Rush" lights up. All output to screen is stopped, and, if in Pause, scrollback will immediately scroll back to the main screen, and stop working. Note that this can NOT happen in the menus. If you quit to the menu, only the XOFF flow control remains active, *if* you selected it or both. During this time, the computer will be chugging away in the background, processing the incoming data as quickly as possible, not displaying it and only saving it into the 2K text mirror of the screen, which is much faster (used in Print-screen, screen refreshes and scrollback). When the buffer has shrunk back to safer proportions, this process stops. (Note that this text-mirror, which is always active, is, like the 8K graphics screen, scrolled "virtually", which means that I'm not actually moving 2K of data around.) -If you were in Pause mode, you won't be able to scrollback. Leaving Pause will refresh and update the screen, after which you will be able to scrollback as usual, but the older history info may have been lost. -If you were in Terminal mode, the screen will freeze during Rush, then suddenly blank and get redrawn. You can then Pause or scrollback as usual. This process can repeat if data keeps coming in quickly. You can try remotely pausing it by typing ^S (Xoff), but that would be done for you anyway if you selected "both" in the flow control menu. (^Q is Xon.) Save configuration: This will save the current settings and the dialing data into D:ICET.DAT. Note that the path setting in the Mini-DOS menu has no effect on where this file is saved. Mini-DOS menu ------------- Disk directory: This will display the directory of the path name you specified. 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 traslated 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. 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 does nothing to files transferred using protocol transfers (X/Y/Zmodem). View file: Read contents of a file in 80 columns. Press the space bar to advance by one page, or Return for one line. 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. Transfer menu ------------- Toggle capture: Enable or disable saving all incoming data into the capture buffer, marked by the "C:" indicator in the terminal. Data will be saved in this buffer when it is displayed (which can occur after it is received). All EOL translation and ANSI stripping, if requested, will occur at that point, and not when saving; Make sure you have the proper settings for these before enabling the capture buffer. 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 after 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 in the buffer. Any data coming in *during* the disk operation will be lost, however, so make sure nothing does. ASCII upload - Send a file to the remote host, with no protocol. You can add a delay between every line sent, or cause the upload to wait for a prompt from the remote host before sending the next line. These two are mutually exclusive. 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. You may request Xmodem-1K (from the host!) if you want - it's faster with a clean line. Remember to set D/L EOL Trans. to "None" before transferring a binary file. Exit to the menus and select this option. The Xmodem protocol doesn't exchange any file information, and 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, and I hope this doesn't cause the host to time out. 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-choice" 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 any extra characters in the last block can be removed. This capability is lost if the file is over 16MB long, but I'm pretty sure you already knew that. 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, 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. I recommend using this protocol only if you have a RAMdisk, hard disk or if your modem is connected through a Black Box or MIO (or similar device). Even with a RAMdisk, Ice-T may have trouble keeping up with the constant data stream at high baud rates. In this case data will be lost, causing an error and aborting the transfer. 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 (very rare, and against the protocol documentation), 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. In fact, this should cause nothing more than a delay. While the protocol supports CRC-16 and CRC-32, only CRC-16 is implemented. To begin a transfer, request one or more files from your host. This will automatically begin the download; you may never actually have to select this option in the menu, unless the sender's initial request to send gets garbled. 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. Quitting the program -------------------- Hit 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 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. 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 modem, and anything received is handled, either as a control command or as a character to be displayed. Pause: 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 Option and Select 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. Note, that only lines that get scrolled out of the top line get saved in this history buffer. If you're scrolling a lower portion of the screen (which is one of the capabilities of the VT100), the text is not retained. Incoming characters also accumulate in the buffer when you are not in Terminal mode. They are displayed when you return to Terminal with Pause off. Print-screen (^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 (^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 (^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. Quit to menu: Press Shift-Esc to quit 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 does not work with keys that send more than one code, like the arrow keys. 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 ^Shift-S Internal speed test used for development (hit any key to stop) Numeric keypad emulation: Codes sent depend on setting of Num-lock, which is indicated in the status-line, and is controlled by a code sent from host. The following used with ^Shift: 0-9 - Numeric-keypad 0-9 Comma, period, minus, - Numeric keypad equivalents Q,W,E,R - PF1,2,3,4 respectively 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, , others not mentioned - as expected - Delete code specified in Parameters menu Shift- - Other delete code, the one you didn't specify. 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 - ^[ (same as Esc) ^period - ^] ^6 - ^^ ^8 or ^space - ^@ (null) ^colon - ^_ ^? - ^? ($7F, DEL) 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 and moral support; John Harris, author of the MAE assembler/editor used for the majority of development; 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 even adding an option at my request; 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 ---------------