*** I did not want to spread this program until it has been *** fully tested - but there were so many people interested *** in this program that I could not make it available to them *** by personal mail. This is still a beta-test version, and *** I'm sure there will still be bugs in there. If you've got *** problems using TWC, don't throw it away, but send me *** a detailed bug-report. I'm honestly interested in making *** TWC an absolutely reliable protocol - please help me to do so. ######### ### ### ###### ######### ### ### ######## ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ############# ######## ### ########### ###### by Lutz Vieweg -*- MANUAL -*- Please excuse linguistic mistakes in the following text - english is not my native language. 0.0 What is TWC? ---------------- TWC is an utility which allows you to transmit files and chat-lines via a serial port in _both_ directions at the same time. 0.1 Why use TWC? ---------------- Most available serial-transfer programs (such as the various terminal-programs etc.) does not allow bidirektional transmission of files, though most modern modems support 'Full Duplex', and are therefore able to transmit data in and out at the same time. Compared to theese programs you can gain a time saving of about 50% when exchanging files. And you may always chat with the guy on the other side of the line... 0.2 Requirements ---------------- If you want to benefit from TWC, you should have the following equipment available: - An Amiga computer running KickStart/WorkBench version 2.04 or higher - A modem featuring at least one real 'Full Duplex' transmission standard. Examples for this are: V.22, V.22bis, Bell 212A, Bell 103, V.21, V.32, V.32bis The following standards are definitely _not_ advisable to be used with TWC: V.23, USR HST, Telebit PEP, Telebit PEP+ - Your modem has to be connected to your computer with a so-called "7-Wire" cable. That means, RTS/CTS handshake has to be possible. Modern high-speed modems are connected with such cables in general. - If your Amiga contains only a 68000 or 68010, and you want to use a high-speed modem along with TWC, you should replace the fucking slow original serial.device by a faster one - as far as I know there's only one replacement called 'BaudBandit' (V1.2) available by now. BaudBandit is (by now) sprinkeld with bugs, but I took care of those bugs and so it should run... - TWC needs a lot of memory, you should have about 400kB free when starting TWC. It also needs a large stack, take a look at the application icon, the neccessary stack size is denoted there. 0.3 Prepare to start TWC ------------------------ If all the requirements in the above paragraph are satisfied, only little things are left to do before you can succesfully start TWC. Whenever you start TWC it looks for two configuration-files, named S:TWC_user_setup and S:TWC_io_setup. If TWC failes to open theese files, it uses the builtin defaults. When you leave TWC, it will write the two files back - if possible and neccesary. In general, TWC should run on your Amiga with the builtin defaults. But it is a good idea to take a look at them with an editor before you make your first connection. Just invoke TWC, and quit it - then you can edit the two files in your s: directory. The most important thing you will want to change in the configuration is the baud-rate to your modem. 19200 baud are the default-value. By default, incoming files are stored in the 'T:' directory - you may want to change that, too. A detailed description of the (mostly self-explanatory) entries in the configuration files is given in a later section of this manual. Did you remember to set your Stack to an appropriate size? :) 1.0 Using TWC ------------- TWC is not difficult to use - operations are completely gadget-driven, and the gadgets shouldn't need any explanation to the advanced user or freak. 1.1 Make a connection --------------------- TWC was designed to serve as a file and chat transfer program for human<->computer<->modem<->phoneline<->modem<->computer<->human connections. Theres no sense in calling a mail-box with TWC, or trying to do TCP/IP with it. This is how you would ordinarily make a connection with TWC: - Start TWC on your Amiga - Call the other human who wants to exchange data with you the conservative (voice) way. Tell him to start TWC at his computer, too. - Tell him to press the 'ATA' button. When you hear the 'click' in the line, press the 'ATD' button. The ATA and ATD buttons simply send commands to your modem. You can change the commands sent out by these buttons in the TWC_user_setup file. You will need to do this for example if you want to make TWC call a phone number automatically or if your modem needs special initialisation commands. You can manually send commands to your modem when the Modem/Chat selector is switched to 'Modem' by simply typing your command and pressing 'enter'. 1.2 The connection is made, now tell the other guy good-morning... :) --------------------------------------------------------------------- In most cases, you'll see a 'CONNECT .....' message in the status-display when all the beeping is over. Everything that is coming from the serial port is evaluated by TWC, and if it's not in TWC's internal format, TWC will print out what came in marking it as junk data ('JUNK> '). If the Modem/Chat selector is switched to 'Chat', you can easily send messages to your opponent by typing them an pressing 'enter'. Your opponent's messages will be displayed in the chat display area at the bottom of the screen. 1.3 Chatting is fine, but now I want to send files... ----------------------------------------------------- I know you could guess it - just click the 'Send File' gadget with your mouse. A file-requester will open, and you can choose the file you want to send to your opponents computer. Some messages in the status-display will inform you what's going on, and if everything went fine, the file will sooner or later be transferred. While the file is transferred, you'll see some statistic data in the status display - enjoy them or ignore them. If you send a file that's partly present in your opponent's incoming directory, TWC will resume the transfer from where you left off. One gadget, labelled 'Abort Sending' will become selectable while the file transfer is in progress. If you abort the transfer by clicking that gadget, there'll appear some 'receiving unexpected data packet' warnings in the status display. That's normal and due to the protocol used. If you want to send more than one file, you don't have to wait for the transmission to complete. Just push the 'Send File' gadget again, and select the next one(s) - it'll be automatically send when possible. The situation on the over side of the line is not different: Your opponent can send files to you at the same time, and what to you is the 'Sending..' ist to him the 'Reception...'. You may also continue to chat at any time - your chat packets are sent to the other side along with the file data. 1.4 Was a nice transfer, but now it's time to leave... ------------------------------------------------------ The close gadget of the command-window and the 'Quit' gadget in it are nearly aequivalent - both will cause TWC to quit. But the state of the 'Quit' gadget (enabled / disabled) will remind you whether there's a file-transfer in progress. You can tell TWC to release the serial port (and thereby hanging up when the modem is properly configured) by clicking the 'Hang Up' gadget. 1.5 My opponent likes multitasking, but I have an urgent thing to tell him.. ---------------------------------------------------------------------------- If the guy on the other side of the line used the time of the transmission(s) to browse through his 1-GigaByte-naked-women-picture-partition, but you need to tell him you just saw Jesus on the chat line, push the 'Ring Other' button - your opponents TWC Screen will be brought to front and be 'beeped'. 1.6 Problems, nothing but problems... ------------------------------------- The only thing one can rely upon in data-transmission is that there will be problems. A lot of problems can be avoided by using proper modems (maybe with V.42, LAPM, MNP e.g.). There will still be problems. Don't mind to much when there appear 'WARNING's in your status display. Most of them will not harm the transmission of your files in any way. They are more interesting for trouble-shooting. 'ERROR's are more severe. They always have a reason you or your opponent could remove. When an 'ERROR' occurs, your file will generally not be transmitted correctly. A few hints that may help you: - If you use an A500 and BaudBandit.device, watch out for trouble. This thing is not that dependable. Try to use a lower baud-rate, if neccessary. - If you use a ZyXEL Modem, don't use the 5.00e ROM-version along with V.42bis compression. - If you use an USR dual standard modem, make sure you have a V.32bis connection. To one-way-only users HST and V.32bis seem to be of the same speed, but THEY AREN'T. - If you use a Telebit Modem, don't use PEP modulation. Use V.32 or even better V.32bis instead. - Don't panic when your V.32bis modems retrain... bad line conditions can cause transfer interruptions up to 20 seconds, especcially with buggy modem-software (such as the early versions of the Rockwell-Chipset used in Supra, Twincom, Yoriko and others) - The greater your modem's buffer is, the longer chat-packets will be delayed - please remember this... 2.0 Yeah, I'm one of those cps-shooting freaks, tell me everything... --------------------------------------------------------------------- The protocol used by TWC is my own development. It was designed to take advantage from full-duplex connections as much as possible. Both sides permanently send out data, without waiting for acknoledgements. The outgoing data is stored in data-structures until an positive acknoledgement is received from the opponent; if a negative acknoledgement is received at any time, the appropriate data block is send out again. Data blocks doesn't have to come in the right order, but 'WARNING's are generated if something seems to be missed - that'll be no tragedy, all correct incoming data blocks are used. My protocol never times out. TWC never get's upset when anything lasts for a long while, because only few things have to be done immediately (the one exception are the file-headers). You may change the config-files as you like, but I don't think you'll get much better results than with the default values. TWC was programmed in C++ using the marvellous GNU C++ Amiga implementation from Markus Wild. This is the reason why TWC isn't that short and needs a lot of stack. 3.0 The detailed description of the configuration files ------------------------------------------------------- The configuration files consist of pairs of two lines: The first one describes the parameter, the second one is the value. Most values aren't checked for bounds, so don't play with them too wild... Don't remove the 'tab's from the beginning of the value lines! And don't add empty or junk-lines! The TWC_io_setup file looks like this. Incoming_Packet_History_Length_Tolerance 10 Maximum_Packet_Size 1016 Maximum_Warnings_until_DisplayBeep 5 Outgoing_Packet_Buffer_Size 20 Path_for_incoming_files T: Priority_of_IO_Watcher_Task 1 Seconds_of_silence_until_AutoHangUp 60 serial_port_SerFlags 148 serial_port_baud_rate 19200 serial_port_device_name serial.device serial_port_device_unit 0 serial_port_read_buffer_length 32768 Incoming_Packet_History_Length_Tolerance is the number of data blocks TWC stores in its incoming packet data structures until it sends out a NACK (negative acknolegdement) for the oldest not correctly received block. There's not much sense in changing this value, it should always be smaller than the Outgoing_Packet_Buffer_Size Maximum_Packet_Size is the amount of file-data-bytes TWC sends with one data packet. You may set this to a lower value (i.e. 500) when using a slow modem, to prevent long delays when chatting Maximum_Warnings_until_DisplayBeep is the number of warnings that will be counted until a display-beep is caused. Outgoing_Packet_Buffer_Size is the number of data blocks TWC stores in its outgoing packet data structures until it stops further sending (because it assumes that the opponent really missed something). Path_for_incoming_files is exactly what you guess it is :) Priority_of_IO_Watcher_Task is the priority of the task maintaining all the I/O stuff. If you want your transmissions not to be delayed by your other applications, set this to something higher than 0. Seconds_of_silence_until_AutoHangUp is the number of seconds TWC waits when nothing happenes (no traffic on the serial port, no commands from the user... nothing at all...) until it automatically hangs up. This is especially of use if you do a great file-transfer with your opponent and don't want to wait for it to finish. serial_port_SerFlags are not to be changed by the ordinary user. Experts may do sensible things with it in seldom cases. serial_port_device_name is the name of the device you want TWC to send the data to. You may put in names like 'BaudBandit.device' in here (case sensitive!) serial_port_device_unit needs no further explanation :) serial_port_read_buffer_length should not be made smaller than the default value. A greater won't hurt. The TWC_user_setup file looks like this: ATA_like_modem_command_string ATA ATD_like_modem_command_string ATH1D Additional_Screen_Heigth 200 Interlace_Mode_? ON Length_of_History 50 Monitor_Type DEFAULT Priority_of_GUI_Task 0 ATA_like_modem_command_string is the command that is send to the modem when you press the 'ATA' button. You may insert other strings here e.g. if you want to make your modem dial etc... ATD_like_modem_command_string is the command that is send to the modem when you press the 'ATD' button. Change it, if your modem needs this. Hint: For USR Modems, insert 'ATX0H1D' here. Additional_Screen_Heigth is the number of lines beyond 200 your TWC screen should show. For non-interlace NTSC, this should be 0, for interlaced NTSC: 200, for PAL: 56, for interlaced PAL: 112. But these values are not a must... Interlace_Mode_? is whether or not you want the screen to be interlaced. Everything but 'ON' is treated as 'OFF'. Length_of_History is the number of lines you want TWC to remember in the chat- and status-display. Monitor_Type could be NTSC for a NTSC-screen, PAL for a PAL-screen or anything else for the default type of screen. Priority_of_GUI_Task is the priority of the task which maintains the user interface. 0 is probably a good choice. 4.0 The legal stuff ------------------- Hey, you really read this chapter? Congratulations, you are one of a few... :) The TWC executable, its icon and this documentation is freely distributable as long as _NO_ money is taken for the copy (so take off your greedy fingers from that program, PD-seller!) The IXEmul.library used by TWC is distributed under the GNU LIBRARY GENERAL PUBLIC LICENSE. Read the file 'COPYING.LIB' for details. And of course, there's no warranty at all. :) 5.0 The adress of the author ---------------------------- Send bug-reports, great improvement ideas, love-letters, brand new computers and all your money to: Lutz Vieweg Eduard-Rüppell-Straße 12 6000 Frankfurt am Main 1 UseNet: lkv@mania.hotb.sub.org FidoNet: Lutz Vieweg, 2:247/30.20 5.1 Thanks go to... ------------------- Markus Wild for the marvellous Amiga implementation of GNU C++ Michael Rohrdrommel for massive testing partnership Dirk Piesker for a lended A600 for testing purposes Wolf Faust for some valuable hints Ulrich Hirner for some testing sessions Anreas Kirchwitz for beta-testing Martin Schulze for lots of ideas 6.0 Version changes history --------------------------- 1.06beta Added time-out feature - please take a look at the description of the setup-variable: Seconds_of_silence_until_AutoHangUp Fixed a dangerous part of the code which could have led to problems when incoming and outgoing chat appeared at the same time 1.05beta The chat-lines you write are now displayed in the chat-display, your opponents chat-lines are preceeded with "> ". (M. Schulze) Errors now cause a display-beep Warnings are counted, if the count reaches the value specified in the new setup variable Maximum_Warnings_until_DisplayBeep this causes a display-beep Major bug fixed: TWC sometimes crashed when it was left Fixed a bug that caused TWC to leave memory unfreed sometimes when the reception of a file was aborted Reduced Code redundancy a little bit... :) 1.04beta New compiler version used: GCC 2.2.2 This requires usage of the new IXEmul-library supplied with this archive... 'inline' code used for library calls Finally, I found & fixed that nasty crippeled-filename bug... Both windows now have depth-gadgets 1.03beta The sreen font is now explicitly set to topaz 8. (A. Kirchwitz) Multi-file-selection is now possible. (A. Kirchwitz) Adding a file to the list of files to send is now reported in the status-display 1.02beta (not released) Finally, the ugly 'ListView'-bug has been fixed. TWC no longer crashes when you scroll one of the lists while TWC tries to output something (Thanks to Michael J.) 1.01beta 'Abort Sending' now tries to make the receiver abort the transmission, if that failes, you may press the button again, and the sending will instantly be aborted. A "/" is now added to the incoming files path name if there's no "/" or ":" in the end. (U. Hirner) cps-Diplay refresh now only when values have changed (W. Faust) Added 'ATD_like_command' for USR Modem 'ATX0H1D' hint to document (W. Faust) The amount of file-data-bytes leaving TWC with one Packet is now changeable in the io_setup file (1 - 1016). Note that this does not change the size of memory allocated for one packet. The priorities of the GUI- and I/O-task are now selectable in the two setup-files. 1.00beta Beta-release for testing purposes only. Yeah, BUGs, I _know_ you hide there.... 8| 6.1 Known bugs -------------- none