* If you've got trouble using TWC, * * take a look at the IFF-ILBM file In_case_of_a_bug.ilbm * ######### ### ### ###### ######### ### ### ######## ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ############# ######## ### ########### ###### 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.4) available by now. BaudBandit is (by now) sprinkeld with bugs, but I took care of those bugs and so it should run... - If you want to use the auto-hangup feature, your modem-cable should include the carrier-detect wire. 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 TWC_user_setup and TWC_io_setup in the directory the executable was loaded from. 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 on your disk. 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. 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. There's 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. BaudBandit 1.4 seems to work fine. - 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. 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. File_write_buffer_length 10000 Maximum_Packet_Size 1016 Maximum_Warnings_until_DisplayBeep 5 Outgoing_Packet_Buffer_Size 10 Path_for_incoming_files T: Priority_of_IO_Watcher_Task 1 Seconds_of_silence_until_AutoHangUp 60 Seconds_of_silence_until_re-sending_outgoing_data 5 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 File_write_buffer_length is the length of the file-write buffer. You may specify any number of bytes, 0 means no buffering at all. 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). Don't set this value too high, because if one data packet or its acknoledgement gets completely lost (not just corrupted), this number of packets is transmitted before TWC tries to resend the lost data. 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 valid packets coming from or going to the serial port, not even chat-packets etc.) 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. Please notice that no auto-hangup will be executed if carrier-detect is not active. Seconds_of_silence_until_re-sending_outgoing_data is the number of seconds TWC waits when no acknoledgements are coming from the receiver until it tries to resend the oldest not-acknoledged packet. If a re-send does not seem to be sensible, because there is already data waiting to leave the serial port, no resend is done, but the user is notified that the line seems to be jammed. 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 number 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 Default_Upload_Directory T: Interlace_Mode_? ON Length_of_History 50 Monitor_Type DEFAULT Name_of_the_fucking_LogFile NoFuckingLogFile! 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: 312. But these values are not a must... Default_Upload_Directory is the directory that is read first when the file-requester is opened. 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. Name_of_the_fucking_LogFile - if you want to waste time and disk-space, insert a filename here. If you're not such a sick one, set this option to "NoFuckingLogFile!" Priority_of_GUI_Task is the priority of the task which maintains the user interface. 0 is probably a good choice. 4.0 The ARexx interface ----------------------- You can control TWC using its ARexx interface easily. The name of the ARexx port is 'TWC.1' for the first opened TWC, 'TWC.2' for the second and so on... 4.1 Overview of available ARexx commands ---------------------------------------- All commands are case-insensitive Quit causes TWC to abort anything and quit. You can QUIT TWC whether transfer is in progress or not. Sendfile adds to the list of files to be send. SENDFILE returns the number of files already in that list to you. Due to the multi-tasking this value can possibly be obsolete when you get it. SwitchToModem Sets the state of the Modem/Chat switch to 'Modem' SwitchToChat Sets the state of the Modem/Chat switch to 'Chat' HangUp Does exactly the same as the 'HangUp' gadget RingOther Does exactly the same as the 'Ring Other' gadget ModemATA Does exactly the same as the 'ATA' gadget ModemATD Does exactly the same as the 'ATD' gadget AbortSend Does exactly the same as the 'Abort Send' gadget (and you may also use this command twice to be sure the transfer is definitely aborted...) AbortReception Does exactly the same as the 'Abort Reception' gadget SendLine Sends either as chatline to the opponent or as command to the modem, regarding the state of the Modem/Chat switch FileOutRem returns the number of bytes still to send for the actual file FileOutPos returns the number of bytes already sent for the actual file FileInRem returns the number of bytes still to receive for the actual file FileInPos returns the number of bytes already received for the actual file FilesToSend returns the number of files that are still to be send LastChatLine returns the last chat-line that has been added to the display. If there was no new chat-line after the last call, an empty string is returned. LastStatusLine returns the last status-line that has been added to the display. Please notice: Any result you get from one of the above commands may be obsolete due to the multitasking-system. 5.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 are freely distributable as long as _NO_ money is taken for the copy (so take off your greedy fingers from that program, PD-seller!) And of course, there's no warranty at all. :) 6.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.robin.de FidoNet: Lutz Vieweg, 2:249/30.20 6.1 Thanks go to... ------------------- Markus Wild for the marvellous Amiga implementation of GNU C++ Michael Rohrdrommel for massive testing partnership (and strange ideas...) 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 dozens of ideas Peter Simons for being an active beta-tester Stefan Scholl for sending me 'StackWatch' 7.0 Version changes history --------------------------- 2.06 There's a principial problem when you try to keep a protocol from timing out in any case: One cannot be sure that anything has reached the other end of the line correctly, so there's no way to ensure that the receiver could initiate a re-send of data at all. On the other hand, timing out is very difficult to do when you don't want to hurt the transmission speed at bidirectional transfers. I hope I found a way to preserve the maximum performance while detecting those cases, where a resend has to be initiated by the sender. But now for the changes you'll see: There's no longer the Incoming_Packet_History_Length_Tolerance setup entry, but a new one called Seconds_of_silence_until_re-sending_outgoing_data This entry is set to 5 seconds by default, and it has the following meaning: Whenever the sender hasn't received any kind of acknoledgement from the receiver for this period of time, it looks wether the data-out channel is ready to send. If not, the sender assumes line noise etc. and just gives a warning - nothing else happenes. If the line is found to be ready to send, the sender looks through the list of non-acknoledged packets, and if there's any, he re-sends the oldest packet from this list, and gives a notification to the user. Please note that this new feature changes the meaning of the setup-entry Outgoing_Packet_Buffer_Size, it is now set to 10 by default, and this means: If, for any reason, one of the data packets in the stream or its acknolegdement got completely lost (not only corrupted), the transmission will continue until the 10th packet from the lost one has been transmitted, then it stops for the time specified by Seconds_of_silence_until_re-sending_outgoing_data, then the sender will resend the lost data-packet and everything will continue correctly (hopefully :) 2.05 From release 2.00 to 2.04, file writing was done using the OS-routine FWrite(). Since this routine uses a very small buffer by default, and the routine to change the buffer size is not implemented in KS 2.04, there has been an annoying time-waste... I've now implemented buffer routines by myself, so this shouldn't be a problem anymore. You can specify the size of the buffer in the TWC_IO_Setup file (see above) Further little changes have been made to the packet priorities to optimize the transmission speed - especially the begin of a file-transfer should now be faster. TWC is now compiled with GNU C++ release 2.3.3. When the I/O watcher process cannot initialize properly (e.g. because the serial device is already in use), TWC won't automatically quit anymore. Instead, it quits when the first message is sent to the GUI-process - this was the only "clean" way I found to handle this kind of fatal error. 2.04 In some cases, when the in- and out-transfer-rates were very different, the data-stream was delayed in the slower direction - this has been corrected by giving data-packet acknoledgements precedence over data-packets. Trash could appear in the cps- and position/remaining displays. This problem has been easily solved... :) 2.03 An annoying little bug has been fixed: The routine stripping the path from a filename was buggy, works properly now... 2.02 Some very important things have been done to improve stability under bad circumstances - TWC now shouldn't crash anymore when garbage comes through the line... 2.01beta Ok, ok, of course there were some bugs in it... :) TWC sometimes crashed when it was invoked while the CPU was very busy - a nasty little bug, fixed now.. The I/O routines worked unbuffered... this was a waste of time... changed now. 2.00beta You'll surely ask: Why the hell is this version called '2.00' - there are in fact _no_ new features... so please let me explain this: Though you might not see it, TWC 2.00 is a major rewrite of version 1.13. Until version 1.13, I used the g++-library coming with GNU C++, which also made use of the c-library and finally the shared IXEmul.library. TWC got very huge this way, and even worse: There were some bugs hard to reproduce that I really couldn't find. So I decided to write my own startup-code, libraries and classes and - voila! - here it is. TWC has become much shorter, it doesn't need the IXEmul.library anymore, and it is (hopefully) more stable. I've named this version "beta" because of two reasons: - I want to wait for GCC 2.3.3 before releasing the non-beta version (currently, 2.2.2 is used) - Since a lot new code has been written, there may hide some new bugs... but if so, I'll now have the chance to find them... :) 1.13 The default upload directory will now only affect the first occurence of the file-requester. 1.12 You are now able to specify a default upload-directory in the user_setup file. New ARexx commands: LastChatLine, LastStatusLine Please take a look at the ARexx command chapter Using theese commands you'll possibly be able to create an ARexx program answering calls automatically. When a hangup is executed, not only the actual file- transfer is stopped now, the "files-to-send" list is cleared also. 1.11beta Now TWC won't crash anymore when the serial port is not available. 1.10beta (This is the first version I encouraged everyone to get and try... I think it is stable enough to do so now) Reduced the required stack size drastically - I still don't know exactly how much stack is required, but StackWatch says < 3000 byte, and so I hope there won't be any crashes with stack sizes of 15000.... (the icon is modified that way..) The setup-files no resides in the actual directory where the executable of TWC has been found - if you used TWC before, please move your setup-files from the s: directory to the appropriate one 1.09beta Added the ARexx-interface. Please read the related chapter above Now an auto-hangup is only executed when carrier-detect is active (please make sure your modem-cable supports carrier-detection) 1.08beta Removed a cosmetic bug that caused TWC to update the cps- and postition information too seldom... 1.07beta Removed a little cosmetic bug that caused TWC to drop the line automatically when there was no necessaty to do so. File transfers are now automatically aborted on hang up Added the absolutely unnecessary log-file feature (M. Rohrdrommel) 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| 7.1 Known bugs -------------- TWC actually leaves 8 bytes of memory unfreed when leaving. I'll try to fix this ASAP.