@database TWC.guide @master "TWC.guide" @author "Lutz Vieweg" @(c) "Copyright © 1993 Lutz Vieweg" @$VER: TWC.guide 1.1 @node Main "TWC ]I[ - the ultimate bidirectional transfer tool" ######### ### ### ###### ######### ### ### ######## ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ### ]I[ ### ### ### ### ### ### ### ### ### ### ### ### ############# ######## ### ########### ###### by Lutz Vieweg -*- MANUAL -*- Topics of this manual: ---------------------- @{"What is TWC?" link Whatis} And why use it? @{"Requirements" link Require} - what you need to run TWC @{"Quickstart" link Quickstart} - a short guide to your first transfer @{"Reference" link Details} with detailed information on any function Invocation from @{"CLI" link CLI} Invocation from @{"Workbench" link WB} @{"Project" link Proj} menu/gadget/ARexx functions @{"Function" link Func} menu/gadget/ARexx functions @{"Setup" link SetupScreen} details @{"Screen" link SetupScreen} setup @{"Serial" link SetupSerial}-device setup @{"Modem" link SetupModem} setup @{"Files" link SetupFile} setup @{"Protocol" link SetupProtocol} setup @{"Process" link SetupProcess} setup @{"Notification" link SetupNotification} setup @{"Audio" link SetupAudio} setup @{"Misc" link SetupMisc} setup @{"ARexx" link ARexx} specific commands @{"Problems" link Problems} and possible solutions @{"Copyright" link Copyright} and how to register TWC @{"Credits" link Credits} to helpful people @{"Programmers" link Pgm} info @{"Version" link Version} history @{"Future" link Future} extensions, just wanna-be's IMPORTANT NOTE TO ALL WHO HAVE BEEN USING TWC 2.06 BEFORE: TWC III is not just another version of TWC, it's a complete rewrite. Not much is the same as before. TWC III is incompatible to versions < 3. @endnode @node Whatis "What is TWC???" If you've got a modem, you'll sometimes want to exchange data with others using it. You can do this with many tools, but they all have their drawbacks. TWC hasn't. :) Most other communication software is designed for calling "Bulletin- Board-Systems", this is not what TWC has been made for. TWC is meant to be the ultimate utility when you want to call another TWC-user, just to exchange some data and chat with him... A short list of features TWC provides (don't mind if you don't understand some of theese, you can benefit from them without knowing) - Extreme reliability and system-friendlyness - Full bidirektional transfer of files, chat-text (and soon even more), can save you up to 50% time and phone-bill - High transfer rates, performs well on bad lines, where other protocols sucks with permanent resends - Low CPU-time usage even at high transfer-rates, example: Bidirectional transfer at 2200+2200=4400cps on an A3000 takes approx. 11% CPU time - Comfortable, font-sensitive GUI - Multi-threaded program structure, asynchronus GUI, disk I/O etc... @endnode @node Require "Requirements - what you need to enjoy TWC" To run TWC you'll need the following things: - An Amiga running KS 2.04 or newer - A modem featuring at least one real 'Full Duplex' transmission standard. If you don't know whether your modem fits, just try it - most modern modems are suitable. Some bidirectional modulation schemes are: V.22, V.22bis, Bell 212A, Bell 103, V.21, V.32, V.32bis, V.32terbo, V.fast The following modulation methods are definitely _not_ advisable to be used with TWC: V.23, USR HST, Telebit PEP, Telebit PEP+ If you've got a modem which normally uses one of theese, make sure to switch to a suitable modulation method with your initialisation command. - 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. The "carrier detect" (CD) wire has also to be connected. Modern high-speed modems are connected with such cables in general. @endnode @node Quickstart "Quickstart - how to make your first connection" Little things have to be done to enjoy your first connection with TWC. If you've got a partner on the phone, who also has a copy of TWC, you might try a real transfer. If you want to test out TWC alone, you can also do that, just read on. Start TWC - now. Invokation can be done either by clicking on the TWC-Icon at the Workbench, or you may start TWC from a CLI or shell by simply typing "TWC" in the directory where you have it. If you start TWC from a CLI, and your stack is too small, a requester will appear and tell you how to change this. You can give TWC filenames as parameters either by passing them through the command-line or by starting TWC with other Icons selected from WorkBench, they'll be put into the "files-to-send" list on startup. The first time you start it, TWC will open a 640*256 Hires screen, with 4 windows on it (the windows may overlap). If you've got a hardware that supports larger screens than 640*256, the first thing you should is: Browse through the "Setup" menu, find the submenu "Screen" and use the commands "Screen Width" and "Screen Height" there to adjust the size. Another menu- command, "Display ID" allows you to change the mode of the screen TWC will open, here are some usual values for this ID: 0x8000 open an ordinary Hires screen 0x8020 open a super-Hires screen 0x8004 open an interlaced Hires screen 0x8024 open an interlased super-Hires screen (For more information on further display-id's refer to the C= include-file "graphics/displayinfo.h") All TWC screen-settings apply only at invocation time, so you should leave TWC now by clicking the "Quit" Gadget, and starting it again. Whenever you leave TWC, it will write its settings back to disk, by default to a file called "TWC_setup" in the same directory where TWC is. So make sure TWC can write to this directory. ... click @{"next page" link Setup} @endnode @node Setup "Visit the setup-menu" Once you're satisfied with the screen, you may arrange the windows at it as you like. Two of them are resizeable - to take advantage from larger screens... Remember, all the changes you make are stored in the setup-file when you leave TWC. Now visit the setup-menu again, and call each of its commands one after each other. If you don't know what a certain value is good for, just leave it as it was by default. There are a few values where it's likely you will want to make a change: Modem/ATA-like command: If you've got a modem with the german "BTZ" you may have bad luck: Some of them are unable to switch from voice to data mode online, so you'll have to config your modem to answer an incoming call automatically, please refer to the modem's manual Modem/ATD-like command: Some modems are dropping the line soon when you give an ATD command... a solution may be using ATX0D instead, but please read your modem's manual on this topic when in doubt... Serial/Baudrate: Adjust this value for your modem. Most modern modems support fixed baudrates, 2400, 9600, 19200, 38400 etc. - the default value here is 19200 which is suitable for the majority of modems nowadays, but you may need to change this, for example, if you've got only a lousy 2400bps modem... please refer to the manual of your modem. You may also want to change the default paths for incoming and outgoing files, but all the other settings are not that important by now. ... click @{"next page" link Connect} @endnode @node Connect "Now establish the connection" When you've gone through the little setup, you may now actually make your first connection. When you've got a partner on the phone-line, he should have started and setup TWC, too. One of yours should now press the "ATA"- Gadget, the other one the "ATD"-Gadget. There should come some strange beeping noise from your modems, then, and a text like "JUNK> CONNECT 14400" or similar should soon appear in the status-window. If not, read the chapter "Problems". If you don't have a partner on the phone to test TWC, you may test it all alone. Use the "Modem/Chat" radio buttons to switch to "Modem" mode. Give your modem the command to enter "loopback-test-mode", this command is "AT&T1" at many modems. The modem should then connect with itself, and everything you send will be mirrored back to you. This way, you can transfer data to yourself... Once the connection is established, you can start sending your partner what you like. Make sure the "Modem/Chat" radio-buttons indicate "Chat". Just type something on the keyboard. The text you type should appear in the string requester at the "Connect-Panel". When you hit the RETURN- key, the text in the requester is send to your partner. A copy is also shown in your "Chat History". Messages from your partner are preceded with a "> " and also shown in the "Chat History". Once you've chatted enough, try a file transfer. Just click the "Add" Gadget in the "TWC Transfer Panel", a file requester will appear and you can select one or more files to be send. After you've made your choice, the files you selected will be listed in the "TWC Transfer Panel". The transfer of those files to your partner does not immedietly start. It actually starts when you click the "START" Gadget. Once you've started the transfer, it will continue until the connection is closed, or you hit the "ABORT Sending" Gadget. To abort a transfer that comes from your partner, you may click "ABORT Reception". If you start a file transfer with TWC, and the receiver has already a file of that name, which is shorter than your's, TWC will assume you want to resume a former interrupted transfer. Now try the feature that's the main difference between TWC and other communication software: You may continue to chat while you exchange files with your partner, you may select more files to be send, and file transmission goes in both directions at the same time which effectively doubles the transfer-rate. ... click @{"next page" link Funny} @endnode @Node Funny "More funny features available" Here are additional functions you may use when you're connected: Connect Panel / Hang Up: Hitting this button drops the DTR outlet of your serial port, causing the modem to go on-hook. If you modem does not hang up when you click this Gadget, please make a change in your modems configuration, refer to your modem's manual for more information on the DTR-behaviour. Connect Panel / Ring Other: If your partner does something in the background while you're transferring files, and you want him to listen, click the "Ring Other" Gadget. The TWC-screen on his computer will then get into front, and a "display-beep" announces your call for attention. ... click @{"next page" link Quit} @endnode @node Quit "How to get rid of TWC" Assumed the inpropable case you want to leave TWC, you've the choice how to do this: The normal way is clicking the "Quit" Gadget or the close-Gadget of the "Connect Panel". Everything is smoothly abandoned, then. A more brutal way to leave TWC is sending it a BREAK signal, for example by pressing CTRL-C in the shell or CLI where you started TWC. Well, there should be little reason to do it the unusual way. Remember, unless you've registered TWC, TWC will automatically quit after approx. 20 minutes. @endnode @node Details "Detailed function reference" The following pages will describe the functions and Options of TWC in a more detailed manner. Gadgets, menus and related ARexx commands are explained together, if they serve a (nearly) identical function. @endnode @node CLI "Options when invoking TWC from a CLI or shell" If you start TWC from the CLI or a shell, you may pass parameters to it (all parameters are optional): TWC [-s ] [-o ] [-x
] [-r] [] are placeholders. The options are: -s You can supply the name of the setup-file TWC should use here. This file may exists or not. TWC will store the setup under the name of the last-read setup-file when exiting. -o Defines a setup-entry, for a more detailed description see @{"ARexx" link ARexx} command SETUP. You can supply as much -o parameters as you like -r Tells TWC to startup, but not to allocate a communication port. This may be a good idea if you want to use TWC as an external protocol driver. -x
Allows you to start TWC with an already opened serial port. This may be of interest only to programmers.
has to be a pointer to a initialised struct IOExtSer, in decimal or hex (e.g. 49152 or 0xc000) IMPORTANT: Don't use or modify your IOExtSer while TWC uses it. The function "HANGUP" will have no effect when TWC uses an external IOExtSer structure. All serial settings will have no influence when TWC uses an external IOExtSer structure. You may pass as much filenames to TWC via the command line as you like, they will appear in the to-send-list. @endnod @node WB "Starting TWC from the Workbench" Just double-click the TWC-icon to start it. You may also click the TWC icon once, click on other icons once, and then on a last icon twice. This will start TWC with the later clicked icons in the files-to-send list. @endnode @node Proj "Gadget-, menu- and ARexx-functions" ARexx commands are case-insensitive, parameters are not. is a placeholder for a parameter supplied with an ARexx command, xxx gives a short description of the parameter. ---------------------------------------------------------------------- Menu : Project / About TWC Gadget: - ARexx : - Displays a short text telling you about the version and the author of the TWC you are currently running. ---------------------------------------------------------------------- Menu : Project / Load Setup Gadget: - ARexx : LOADSETUP Resets the current settings to the default-values, then tries to load a new setup-file. When TWC exits, and any changes have been made to the setup, the setup is written back to the file where it has been loaded from. Note: The setup file TWC uses is human-readable and "human-editable" - you can load it with any text editor and edit it, if you like. ---------------------------------------------------------------------- Menu : Project / Save Setup Gadget: - ARexx : SAVESETUP Stores the current setup into the file you specified. TWC will store the setup again under the same name when any changes are made until exit. ---------------------------------------------------------------------- Menu : Project / Quit Gadget: Quit ARexx : QUIT Exits the program. Of course, all files currently open are closed etc, but if transfers are in progress when you quit the program, your partners TWC may keep trying to send or receive data, so it's a good idea to end the transfers before you quit. ---------------------------------------------------------------------- @endnode @node Func "Gadget-, menu- and ARexx-functions" ---------------------------------------------------------------------- Menu : Function / Originate (ATD) Gadget: ATD ARexx : ATD Sends a command to your modem causing it to go off hook and listen to carrier tones from the remote modem. When a connection could be established, the modem will answer with a message like "CONNECT 14440" or similar, and you'll then be able to send and receive data to/from the remote modem btw. your partner on the other end of the line. The command that is send to your modem can be configured with the @{"Setup / Modem / ATD-like command" link SetupModem} menu item. ---------------------------------------------------------------------- Menu : Function / Answer (ATA) Gadget: ATA ARexx : ATA Sends a command to your modem causing it to go off hook and send carrier tones to the phone-line. When a connection could be established, the modem will answer with a message like "CONNECT 14440" or similar, and you'll then be able to send and receive data to/from the remote modem btw. your partner on the other end of the line. The command that is send to your modem can be configured with the @{"Setup / Modem / ATA-like command" link SetupModem} menu item. IMPORTANT: - To make a connection, one of the modems on the line has to act as "originator", the other as "answerer". In most cases, it doesn't matter which is which, but there won't be any connection if both modems try to originate or answer a call - Establishing the connection can take some time, up to 20 seconds. While the modems are trying to connect, strange noise is coming from their speakers. This is entirely normal. Please don't send any data to the modem while it is trying to connect, it would instantly give up the try. ---------------------------------------------------------------------- Menu : Function / Dial Number Gadget: Dial ARexx : DIAL Sends a command to your modem causing it to dial the specified number and establish a connection, then some data is sent to the remote to identify the caller as TWC. This feature is sort of useless when communicating with a human partner, it is meant for future support of BBS'es that allow users to login in with TWC. The command that preceeds the number to make your modem dial can be configured with the @{"Setup / Modem / ATA-like command" link SetupModem} menu item. ---------------------------------------------------------------------- Menu : Function / Hang Up Gadget: Hang Up ARexx : HANGUP Closes the connection to the remote modem, the modem will go on hook, and all transfers currently in progress will be aborted. IMPORTANT: - Your modem has to close the connection "when DTR drops" - this is a feature available with any modem, but for any reason, your modem might be configured not to do so. If your modem does not go on hook when you initiate a hang up, you should consult your modems manual and adjust the modem initialisation command according to it. ---------------------------------------------------------------------- Menu : Function / Ring other Gadget: Ring ARexx : RING Sends a very small data-packet to your partner causing his TWC to notify your request for attention. This is by default done by bringing the TWC screen to the front and flashing its background color. ---------------------------------------------------------------------- Menu : Function / Add File Gadget: Add File ARexx : ADDFILE Adds a filename to the list of files to be send (which is displayed in the window called "transfer panel"). If a connection is established and another file has already been sent, TWC will instantly begin the transmission. Otherwise, it will remain in the list until the transfer is started and all preceding files have been transmitted. ---------------------------------------------------------------------- Menu : Function / Start Transmission Gadget: START ARexx : START Starts the transmission of the files in the "to-send"-list. This is only possible if a connection is already established. Once the transfer is started, all files in the list are transferred one after each other until the list is empty. ---------------------------------------------------------------------- Menu : Function / Protocol Status Gadget: - ARexx : PROTOCOLSTATUS Diplays some information on the current protocol status in the status window. This is sort of uninteresting to the ordinary user, but it might help me to locate a bug if any problems are occuring at the transfer... ---------------------------------------------------------------------- Menu : Function / Abort Reception Gadget: Reception (below the text "ABORT") ARexx : ABORTREC When your TWC is receiving a file, and you apply this function, the sender will be asked to stop the transmission. In general, the sender should abort transfer to your TWC then within a few seconds, but if, for any reason, the sender does not stop sending, you may apply the Abort Reception function a second time, then the reception will end immediately, without waiting for sender. ---------------------------------------------------------------------- Menu : Function / Abort Sending Gadget: Sending (below the text "ABORT") ARexx : ABORTSEND Stops the transmission of the file your TWC currently sends. ---------------------------------------------------------------------- Menu : Function / Send File as Chat Gadget: - ARexx : - Sends the contents of a file to your partners TWC as if you typed it into the input line. This feature may sometimes be useful when you want to send your partner e.g. the listing of a directory, a short readme or alike. The filesize is limited to 10kB. ---------------------------------------------------------------------- Menu : Functions / Send Sound File Gadget: - ARexx : SENDSOUNDFILE Sends the contents of an 8SVX (IFF) sound-file to your partners TWC, there it will be played back if sound is enabled. This function is - apart from its testing purposes - just a little joke. The sound is treated the same way as if it where actually coming from a sampler. The same online compression/decompression is applied as it is to "voice chat". IMPORTANT: - If the sample rate of your sound divided by the compression factor is higher than the CPS-rate your modems achieve, the sound will be played back with nasty "gaps". See @{"Setup / Sound" link SetupSound} for details. ---------------------------------------------------------------------- @endnode @node SetupScreen "Gadget-, menu- and ARexx-functions" Note: The placeholder means "x or y" Example: <"YES"|"NO"> means provide "YES" or "NO" as parameter Note: When supplied as parameters, "YES", "Y", "ON" and "NO", "N", "OFF" (all case-insensitive) are synonyms. ---------------------------------------------------------------------- Menu : Setup / Screen / Open on PubScreen Gadget: - ARexx : SETUP "open_GUI_on_public_screen" <"YES"|"NO"> Decides whether TWC should open its GUI on a "public screen" rather than on a custom screen. IMPORTANT: - All screen-settings take effect only on startup, quit and restart TWC to apply them. ---------------------------------------------------------------------- Menu : Setup / Screen / PubScreen Name Gadget: - ARexx : SETUP "public_screen_name" "" Defines the name of the public screen TWC should open its GUI upon, when this is enabled. The default name is "Workbench", that is the screen where the workbench, shells etc. resides. IMPORTANT: - All screen-settings take effect only on startup, quit and restart TWC to apply them. ---------------------------------------------------------------------- Menu : Setup / Screen / Screen Width Gadget: - ARexx : SETUP "screen_width" "" Defines the width of the custom screen TWC should open its GUI upon, when this is enabled. The default width is -1, this means: The standard width that is defined within the preferences tool. IMPORTANT: - All screen-settings take effect only on startup, quit and restart TWC to apply them. ---------------------------------------------------------------------- Menu : Setup / Screen / Screen Height Gadget: - ARexx : SETUP "screen_height" "" Defines the height of the custom screen TWC should open its GUI upon, when this is enabled. The default height is -1, this means: The standard height that is defined within the preferences tool. IMPORTANT: - All screen-settings take effect only on startup, quit and restart TWC to apply them. ---------------------------------------------------------------------- Menu : Setup / Screen / Display ID Gadget: - ARexx : SETUP "screen_display_id" "" Defines the mode of the custom screen TWC should open its GUI upon, when this is enabled. The ID's possible values may not be known to you, here are some examples: 0x8000 open an ordinary Hires screen 0x8020 open a super-Hires screen 0x8004 open an interlaced Hires screen 0x8024 open an interlased super-Hires screen I know it is not very comfortable to choose the screen mode this way, but KS 2.04 does not know any standard screen-mode requester. There may be a requester in future releases of TWC... IMPORTANT: - All screen-settings take effect only on startup, quit and restart TWC to apply them. ---------------------------------------------------------------------- @endnode @node SetupSerial "Gadget-, menu- and ARexx-functions" ---------------------------------------------------------------------- Menu : Setup / Serial / Baudrate Gadget: - ARexx : SETUP "serial_device_baud_rate" "" Sets the baudrate from your computer to your modem. With all modern modems, this baudrate has not to be the same as the rate between your modem and the remote modem. Older modems may require the same baudrate between the modem and the computer as they use to the remote modem. Choosing the optimal baudrate to your modem is one of the more easy things: The higher, the better. When you encounter trouble, lower the baudrate. On 68000-driven Amigas you won't be able to achieve more than 19200 baud to your modem unless you use a non-standard serial-device such as the "BaudBandit.device", see below. On faster Amigas, the baudrate should normally be the highest one your modem supports. Please consult your modems manual to check for the baudrates your modem supports, often used values are: 2400, 9600, 19200, 38400, 57600, 115200 etc.. ---------------------------------------------------------------------- Menu : Setup / Serial / Device Gadget: - ARexx : SETUP "name_of_serial_device" "" Defines the name of the device TWC should open as communication channel. The standard device that drives the Amiga's serial port is called "serial.device" and should reside in your devs: directory. You may use any device with TWC that acts similar to the "serial.device". By now, the only important alternative I know is the "BaudBandit.device", which may enable users of slow Amigas to use baudrates > 19200. On faster Amigas, the original "serial.device" seems to be the better choice. ---------------------------------------------------------------------- Menu : Setup / Serial / Unit Gadget: - ARexx : SETUP "serial-device_unit_number" "" Defines the unit TWC should open the device with. This is important to users with multi-serial cards only, if you don't have such, leave this value 0. ---------------------------------------------------------------------- Menu : Setup / Serial / Flags Gadget: - ARexx : SETUP "serial-device_flags" "" Defines the flags TWC should open the device with. If you don't know what this value could be good for, please leave it as it is. Advanced Amiga users may for any reason wish to make changes here, but don't expect TWC to run perfectly without flow control... ---------------------------------------------------------------------- Menu : Setup / Serial / Buffer Size Gadget: - ARexx : SETUP "serial-device_read_buffer" "" Defines the size of the buffer the serial device provides for incoming data. 32768 seems to be a sufficient size, don't make the buffer too small, higher values won't hurt. ---------------------------------------------------------------------- @endnode @node SetupModem "Gadget-, menu- and ARexx-functions" ---------------------------------------------------------------------- Menu : Setup / Modem / ATA-like command Gadget: - ARexx : SETUP "ATA-like_modem_command" "" Defines the command string to be send to your modem when using the "ATA"-function. This is, by default, the string "ATA\r\n", the "\r" stands for "carriage return", the "\n" for "newline". If you've got any trouble with the default setting, refer to your modems manual for further information, topic "answering calls". ---------------------------------------------------------------------- Menu : Setup / Modem / ATD-like command Gadget: - ARexx : SETUP "ATD-like_modem_command" "" Defines the command string to be send to your modem when using the "ATD"-function. This is, by default, the string "ATX0D\r\n". If you've got any trouble with the default setting, refer to your modems manual for further information, topic "originating calls". ---------------------------------------------------------------------- Menu : Setup / Modem / Dial command Gadget: - ARexx : SETUP !!! Defines the command that should precede the number you supply to the dial function. This is, by default, the string "ATD". If you've got any trouble with the default setting, refer to your modems manual for further information, topic "dialing out". ---------------------------------------------------------------------- Menu : Setup / Modem / Initial command Gadget: - ARexx : SETUP "modem_initialisation_command" "" Defines the command that should be send to your modem whenever the serial device is opened. This is, by default, the string "AT\r\n", a command, that does nothing but tell the modem to answer with "OK". You might want to insert something meaningful here, to configure your modem to work best with TWC. One example: If you've got an US Robotics Courier Dual Standard modem, you should insert "ATB0\r\n" here. Refer to your modems manual for further information. ---------------------------------------------------------------------- @endnode @node SetupFile "Gadget-, menu- and ARexx-functions" ---------------------------------------------------------------------- Menu : Setup / Files / Incoming path Gadget: - ARexx : SETUP "path_for_incoming_files" "" Defines the directory path where to put incoming files at. IMPORTANT: - If you use this function from ARexx, please make sure your path name ends with a "/" or ":" ---------------------------------------------------------------------- Menu : Setup / Files / Outgoing path Gadget: - ARexx : SETUP "path_for_outgoing_files" "" Defines the pathname that occurs in the file-requester the first time you use it. Of course you may send files from any other directory. ---------------------------------------------------------------------- Menu : Setup / Files / Bump filenames Gadget: - ARexx : SETUP "bump_filenames" "" Decides whether or not the names of incoming files should be modified when there already is a file with the original name. The modification is only done if the file that exists is the same length or longer than the incoming file. The modification applied is just the addition of a suffix, a point with a number following it. Example: original file "foobar" exists, bumping is enabled. The incoming file will then have the name "foobar.2". If "foobar" and "foobar.2" exists, the incoming file will be named "foobar.3" etc. ---------------------------------------------------------------------- Menu : Setup / Files / Keep partial files Gadget: - ARexx : SETUP "keep_partial_files" "" Decides whether or not to keep files that have been received incomplete. If disabled, this option will cause deletion of incomplete files, but this makes resuming of an aborted transfer impossible. ---------------------------------------------------------------------- Menu : Setup / Files / Write buffer size Gadget: - ARexx : SETUP "file_write_buffer_size" "" Defines the size of the buffer that is used to hold the data until it is stored into a file. This does NOT mean that data is lost when more has been received than could be written to the file. Incoming data is buffered as necessary, maybe until the whole memory is filled. This value only says: "Don't write incoming data immediately to the file, instead collect it until you received xxx bytes of data, then write the buffer to the file". This is done for efficiency reasons, storing small amounts of data is mostly a waste of time. ---------------------------------------------------------------------- @endnode @node SetupProtocol "Gadget-, menu- and ARexx-functions" Menu : Setup / Protocol / Max. Packet Size Gadget: - ARexx : SETUP "maximum_packet_size" "" Tells TWC how many data-bytes should be bundled in one data-packet. Values higher than 1016 are not possible, and not sensible, I think. Large blocks results in greater delays for the chat-lines you send, small blocks result in more protocol overhead, and therefore lower transfer-rates. It's a question of taste what you prefer. When you've got to use a slow 2400bps modem, you should use a smaller packet size than 1016. When your communication channel is often disturbed, smaller packets may increase the transfer-rate by decreasing the amount of data that has to be resend after an error. Most modern modems do error-correction by themselves, so this is not a point. ---------------------------------------------------------------------- Menu : Setup / Protocol / Resend Timeout Gadget: - ARexx : SETUP "seconds_until_packet_resend" "" TWC is not as stupid as many other protocols that need the data to come in the correct order, packet by packet. Those protocols suffer from corrupted data heavily, the data rate dramatically decreases. Not so with TWC. TWC takes the incoming data-packets regardless of their order. Corrupted data-packets are resend at any later time, TWC stores all the packets internally until it has the opportunity to write sequential data to the incoming file. There are situations, where the receiver is unable to order a corrupted data-packet again, for example, because the negative acknolegdment got corrupted itself. This case is handled by a timeout the sender triggers when a data-packet hasn't been acknolegded for a certain period of time. That doesn't mean the sender gets in panic, then... the unacknolegded data-packet is just transferred again. You can adjust the described timeout to fit your situation. A larger timeout may result in a larger internal array of unacknolegded packets, and in more time-waste when there are unacknolegded packets at the end of a transfer. A smaller timeout may result in unneccessary resends of data under bad circumstances, when the line is jammed. Experiment with this value, if you like. ---------------------------------------------------------------------- Menu : Setup / Protocol / Hangup Timeout Gadget: - ARexx : SETUP "seconds_until_auto_hangup" "" One should be able to start a file-transmission and then leave the computer without having to worry about huge phonebills. So I implemented a timer that causes the connection to be closed when there has been no valid packet been transmitted for a certain period of time (data-packets do not count, because they are resend automatically, but data-acknolegdements count...). ---------------------------------------------------------------------- @endnode @node SetupProcess "Gadget-, menu- and ARexx-functions" ---------------------------------------------------------------------- Menu : Setup / Process / GUI Priority Gadget: - ARexx : SETUP "priority_of_GUI_process" "" Defines the priority of the GUI-process. 0 is the default, you may have your reasons to change this. GUI Priority should generally be lower than serial and disk I/O priority. ---------------------------------------------------------------------- Menu : Setup / Process / Serial I/O Priority Gadget: - ARexx : SETUP "priority_of_serial_I/O_process" "" Defines the priority of the process that handles all the serial in/out operations. This priority should generally be higher then disk I/O and GUI priority ---------------------------------------------------------------------- Menu : Setup / Process / Disk I/O Priority Gadget: - ARexx : SETUP "priority_of_disk_I/O_process" "" Defines the priority of the process that reads/write outgoing/incoming files. This priority should generally be higher then GUI priority and lower than the serial I/O priority. ---------------------------------------------------------------------- Menu : Setup / Process / Audio Play Priority Gadget: - ARexx : SETUP "priority_of_audio_play_process" "" Defines the priority of the process that decompresses and plays incoming sound packets. It's a matter of taste whether to give a higher priority to the audio replay process or the serial I/O process, the default priority is 2 here. ---------------------------------------------------------------------- Menu : Setup / Process / Audio Sample Priority Gadget: - ARexx : SETUP "priority_of_audio_sample_process" "" Defines the priority of the process that samples and compresses the sound. This process needs a high priority to make sure the computer listens when you speak... ---------------------------------------------------------------------- @endnode @node SetupNotification "Gadget-, menu- and ARexx-functions" ---------------------------------------------------------------------- Menu : Setup / Notification / On new chat Gadget: - ARexx : SETUP "on_new_chat_screen_to_front" "" Decides whether or not you want the TWC screen to become the frontmost when new chat texts arrive. ---------------------------------------------------------------------- Menu : Setup / Notification / On end of transfer Gadget: - ARexx : SETUP "on_end_of_transfer_screen_to_front" "" Decides whether or not you want the TWC screen to become the frontmost when all selected files have been transferred. ---------------------------------------------------------------------- Menu : Setup / Notification / Warnings until beep Gadget: - ARexx : SETUP "warnings_until_display_beep" "" Defines the number of warnings to occur before notification. A warning doesn't mean that the transfer fails. It just reports something that would better not be. Errors cause the screen to be "beeped", and you can tell TWC to beep the screen also when a certain amount of warning were displayed. Just a matter of taste. ---------------------------------------------------------------------- Menu : Setup / Notification / Verbosity level Gadget: - ARexx : SETUP "verbosity_level" "" People with little knowledge are often confused by detailed technical descriptions of what's going on. If you don't want to see detailed reports of each and any thing that happenes, lower this value. If you are curious, and need to know what extra-ordinary things happen, increase this value. Sensible values range from 0 to 20. ---------------------------------------------------------------------- @endnode @node SetupAudio "Gadget-, menu- and ARexx-functions" IMPORTANT: Sound support is not completely implemented in the current version, you may transfer IFF-8SVX-files, but the main feature, the sampler support, is not ready. Hold on for the next release... ---------------------------------------------------------------------- Menu : Setup / Audio / Sound Enable Gadget: - ARexx : SETUP "sound_enable" "" Decides whether or not incoming sound should be replayed on your Amiga. If you disable sound, incoming sound packets will simply be ignored. ---------------------------------------------------------------------- Menu : Setup / Audio / { No Compression, ADPCM-2, ADPCM-4 } Gadget: - ARexx : SETUP "sound_compression_method" "<0|2|4>" Selects the sound compression method to be used. Without compression, the sample-rate you can transmit over the communication channel is limited to the CPS-rate you get when transferring files, e.g. about 1600 samples/sec on a V.32bis link. As you may imagine, such a low sample rate is no good for understandable speech. TWC can compress and decompress sound-data "on the fly", thus making higher sample rates possible. The default sound-compression is ADPCM-2, this one compresses 4 bytes of sound samples into 1 byte, allowing for sample-rates up to 6400 Hz on a V.32bis link. Sound compression is "lossy", but will surely sound better than uncompressed sound on the lower rate. If you've got a very fast connection (e.g. an ISDN device, or a NULL-modem cable), you may disable sound- compression, this saves you some CPU-time. ---------------------------------------------------------------------- Menu : Setup / Audio / Sample Rate Gadget: - ARexx : SETUP "audio_sample_rate" "" Defines the number of sound samples to take per second. The higher this rate, the better the sound quality will be, but the sample rate is limited by the speed of the connection (see above). The default value here is 6000, allowing permanent transmission of understandable speech over a V.32bis connection. If you choose a too high sample rate your partner will hear nasty "gaps" in the replay of the sound. The sample rate does not affect IFF-8SVX-files that are transferred. ---------------------------------------------------------------------- Menu : Setup / Audio / Sample Rate Gadget: - ARexx : SETUP "audio_sample_rate" "" Defines the number of sound samples to take per second. The higher this rate, the better the sound quality will be, but the sample rate is limited by the speed of the connection (see above). The default value here is 6000, allowing permanent transmission of understandable speech over a V.32bis connection. If you choose a too high sample rate your partner will hear nasty "gaps" in the replay of the sound. The sample rate does not affect IFF-8SVX-files that are transferred. ---------------------------------------------------------------------- Menu : Setup / Audio / Sample HotKey Gadget: - ARexx : SETUP "sample_hotkey" "" Defines the hotkey that enables sampling. With TWC, you should be able to talk to your partner _while_ files are transferred. As you may imagine, it would be a huge waste of transmission bandwidth if TWC would permanently sample and transmit sound data. To obey this, the sample hotkey works like the send-switch on a radio set. As long as you hold down the hotkey, the sound-sample is taken. If the hotkey is released, no sampling is done. For a description of the parameter see @{"Key Descriptions" link KeyDesc}. The default sample hotkey is "F9". ---------------------------------------------------------------------- @endnode @node SetupMisc "Gadget-, menu- and ARexx-functions" ---------------------------------------------------------------------- Menu : Setup / Misc / Encryption key Gadget: - ARexx : SETUP "encryption_key" "" Defines the encryption key. If you supply no encryption key, encryption is disabled. Phone lines are not safe. It's sort of easy for other people to spy on your communication, and you may not want them to do so. Whether you need to keep your data secret or you're just a little paranoid doesn't matter, this option allows you to make TWC scramble all the data it transfers. Your partner has to set exactly the same encryption key to enable TWC to unscramble your data. Of course it's nonsense to tell your partner the encryption key on the phone that might be spyed... :) Data scrambling needs some extra CPU time. IMPORTANT: Don't change the encryption key while a transfer is in progress. If you experiment with encryption, remember to disable it next time if necessary. ---------------------------------------------------------------------- Menu : Setup / Misc / Display average CPS Gadget: - ARexx : SETUP "show_average_instead_of_actual_CPS" "" Switches display between average and "actual" CPS (chars per second) rates. By default, the CPS displays in the "File Transfer Panel" are integrating over time. This results in a relative stable CPS display, that does not react heavily on temporary changes of the transfer-rate. You can also have TWC to always compute an "actual" CPS-rate, based on the time the last data-packed needed for transfer. This "actual" value is nonsense for the sending-rate when your modem uses packet-oriented protocols such as LAPM, V42 or MNP internally, because the speed depends then on the fill-state of the modems buffer. ---------------------------------------------------------------------- Menu : Setup / Misc / Echo Your Chat Gadget: - ARexx : SETUP "echo_your_chatlines" "" Decides whether or not TWC displays the chatlines you send to your partner in the chat-history. This feature is especially useful if you want to control TWC via ARexx, and you need to evaluate the incoming chat lines. By disabling the echo, you can make sure that only the chat lines coming from the remote TWC are received by the ARexx command @{"GETCHATLINE" link ARexx}. ---------------------------------------------------------------------- Menu : Setup / Misc / ScreenToFront hotkey Gadget: - ARexx : SETUP "screen_to_front_hotkey" "" Defines the hotkey that brings the TWC screen to front temporarily. As long as you hold down this key, the TWC screen stays in front, so you can watch its contents, click a gadget on it etc. This is especially useful if you're doing something on another screen and just want to take a short look at what TWC's doing. For a description of the parameter see @{"Key Descriptions" link KeyDesc}. The default screen-to-front hotkey is "F10". ---------------------------------------------------------------------- Menu : Setup / Misc / Serial Number Gadget: - ARexx : SETUP "ü" "" This is where to enter the serial number you get when you register TWC. The default value here is 0, causing TWC to display a requester telling you about the ShareWare status on startup. If you don't want to see this requester anymore, enter any non-0-number here. But as long as this number is not a valid serial number, TWC will quit automatically after approx. 20 minutes. For detailed information on the ShareWare-status of TWC and how to register, see @{"Copyright" link Copyright}. ---------------------------------------------------------------------- @endnode @node KeyDesc "Format of key descriptions" Some functions of TWC needs key-descriptions. Here are some examples which show how to create such a description: Description Meaning -------------------------------------------------------------------- x The key 'x' SHIFT a The key 'a' while SHIFT is hold down LSHIFT b The key 'b' while the left SHIFT key is hold down RSHIFT c The key 'c' while the right SHIFT key is hold down ALT d Now make a guess! LALT e ... RALT f AMIGA g LAMIGA h RAMIGA i CAPSLOCK j CTRL k NUMPAD 9 The key '9' on the numeric pad. CAPS l BACKSPACE COMMA CURSOR_DOWN CURSOR_LEFT CURSOR_RIGHT CURSOR_UP DEL ENTER ESC F1 F2 .. F10 HELP RETURN SPACE TAB SHIFT CTRL o Combinations are also possible! I hope theese examples are explaination enough... @endnode @node ARexx "ARexx specific commands" The ARexx-port of TWC has the name "TWC.x" where x is a number incremented by any newly started TWC. So the first TWC started has the ARexx-port "TWC.1". IMPORTANT: Unlike many other programs, TWC has an asynchronus ARexx interface. This means: The ARexx commands generally return immediately, but the execution may happen somewhat later. The reason should be obvious: One could not react on incoming data whilst waiting for some other data to went out and vice versa, many other situations are alike. If not mentioned otherwise, assume any command to return immediatly. If an ARexx command fails, an error message can be found in a variable called ".LASTERROR", for the first started TWC e.g. "TWC.1.LASTERROR". Results from ARexx functions are returned in a variable called "RESULT" if you enabled results with the command "options results" (see ARexx guide). Many ARexx functions are already explained above, the following is a list of functions not available from the user interface: ---------------------------------------------------------------------- GETSTATUSLINE Returns the oldest status-line the status-history contains, and removes this line from the history. The history-buffering is necessary to enable you to get any status-line without missing one. ---------------------------------------------------------------------- GETCHATLINE Returns the oldest chat-line the chat-history contains, and removes this line from the history. The history-buffering is necessary to enable you to get any chat-line without missing one. If you want to get only chat-lines that came from the remote TWC, refer to @{"Setup / Misc" link SetupMisc} / Echo your chat. ---------------------------------------------------------------------- SENDMODEM Sends a text to the modem, just as if it where entered by the user while the "Modem" radio-button is selected. A carriage-return + newline is automatically added to your text. ---------------------------------------------------------------------- SENDCHAT Sends a chat-text to the remote TWC, just as if it where entered by the user while the "Chat" radio-button is selected. ---------------------------------------------------------------------- CLEARFILES Removes all files from the to-send-list. The names of the files in the list are returned, delimited by spaces, and enclosed in double-quotes. ---------------------------------------------------------------------- SETUP Allows you to define any setup-value. Each entry in the setup has a name and a value. Just take a look at the TWC_setup file for possible names. IMPORTANT: If you supply an non-existing entry name, a new entry is created (and stored within the setup-file). This is done for forward/backward compatibility. Please avoid to add nonsense-entries to the setup. ---------------------------------------------------------------------- READSETUP Allows you to read any setup-value. Each entry in the setup has a name and a value, the value to the entry supplied is returned by this function. Just take a look at the TWC_setup file for possible names. IMPORTANT: If you supply an non-existing entry name, a new entry is created (and stored within the setup-file). This is done for forward/backward compatibility. Please avoid to add nonsense-entries to the setup. ---------------------------------------------------------------------- REOPENSERIAL If the user changes the serial settings with the GUI, the port is automatically reopened. This does not happen if you change the serial parameters from ARexx. You have to call this function to reopen the serial port from ARexx. ---------------------------------------------------------------------- RELEASESERPORT Tells TWC to release the serial port. The port is reopened by the REOPENSERIAL command. Many TWC functions cannot be executed while the serial port is released. IMPORTANT: Remember that even this command works asynchronusly, make sure that the serial port is actually released before trying to open it from somewhere else. ---------------------------------------------------------------------- WAIT This function does _not_ return immediatly. It allows you to put your ARexx program in a waiting state (consuming no CPU time) until one of a set of events happen. Events that cause WAIT to return are: - New status- or chat-line output - TWC got an ARexx command (maybe from another process) - TWC quits ---------------------------------------------------------------------- EXTERNALPORT
Defines the address of an already initialised struct IOExtSer TWC should use instead of a self-opened device. The address has to be a decimal- or hex-number (e.g. 49152 or 0xc000). IMPORTANT: Don't use or modify your IOExtSer while TWC uses it. The function "HANGUP" will have no effect when TWC uses an external IOExtSer structure. All serial settings will have no influence when TWC uses an external IOExtSer structure. EXTERNALPORT will take effect with the next REOPENSERIAL Note: If you want to use TWC as an external protocol driver, you may make it this way: - start TWC in the background with the -r flag (released port) - when you want to transmit files, use EXTERNALPORT and REOPENSERIAL to prepare TWC for action - use all the other ARexx commands to do the actual transfer - use RELEASESERPORT to detach TWC from your structure ---------------------------------------------------------------------- @endnode @node Problems "Problems - ask Murphy, why." This chapter will grow with the feed-back I get from you and all the other TWC users. Questions unasked cannot be answered... A few hints that may help you: - You start the file transfer, but it doesn't start immediatly, but after the first resend of the file-header. This may result from either a buggy serial.device or some ugly modems. I don't have a clue how to work around this, yet... - If "HangUp" doesn't work, take a look at your modem's configuration. Your modem should hangup when DTR is dropped. - 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. Use ATB0 to enable V.32bis - 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) - If you're transmitting over really bad lines (such as the german BundesPest Telekotz often provides), and your average cps-rate drops below the value (physical bps rate)/10 you may try to switch off the error-correction (V42, MNP4) of your modem. This may sound weired, but TWC's error correction is smarter than the one used in most modems, and you may gain higher rates... (USR Modems: AT&M0) - The greater your modem's buffer is, the longer chat-packets will be delayed - please remember this... as I'm unable to change this... If you've got other problems or solutions, please send a report to my UseNet address lkv@mania.robin.de @endnode @node Copyright "Copyright and how to register TWC III" TWC III has been written by Lutz Vieweg. ©1993, all rights reserved. The TWC executable and documentation is freely distributable, the serial-number you get when you register is NOT. Remember this serial-number will be stored in the setup-file, so don't give anyone a copy of yours. TWC comes without any warranty at all, use at your own risk. To register your TWC and get an individual serial-number send me a letter with US$ 15 in _cash_ + $3 for postage if I can't send you the serial-number via email (UseNet). You may also send me DM 20,- (+ 1DM for postage) if you're living in germany. Once you enter your valid serial-number in the setup menu, TWC won't quit after approx. 20 minutes anymore... Send your registrations, feed-back, ovations etc. to: Lutz Vieweg Eduard-Rüppell-Straße 12 60320 Frankfurt am Main GERMANY UseNet: lkv@mania.robin.de Remember: A bug that's not reported cannot be fixed. (The following does not apply to anyone except to some guys that are having weired and childish discussions on the german UseNet, so don't mind if you cannot read it) DISCLAIMER: Hiermit sei es ausdrücklich gestattet diese ---------- Software zu all jenen Dingen zu gebrauchen, die kleinkarierte Dogmatiker ihren potentiellen Kunden verbieten wollen, also beispielsweise die Übertragung der Wasserstoffbombenkonstruk- tionsunterlagen an Killer-Mutanten vom Mars oder der Verkauf an Arme, die der kostenfreien Beschaffungsmöglichkeiten von ShareWare unkundig sind. Ungeachtet dessen möge derjenige zu Staub zerfallen, welcher seine Seriennummer weitergibt... @endnode @node Credits "Credits to some helpful people" I want to thank the following people for supporting me while TWC was programmed: van den Baard, Jan for "GadToolsBox" which was used to design the GUI Friedl, Henning for valuable programming hints Rohrdrommel, Michael for endless testing sessions on his antique A500 :) Wild, Markus for the marvellous Amiga-implementation of GNU C++ (though I used my own, independent library and startup-code, not the GNU-stuff) ... and of course anyone who reported bugs or registered! @endnode @node Pgm "Infos for programmers" I'd really like to see other programs, especially BBS-softare, to support TWC not only as another transfer protocol, but a advanced and more comfortable way to exchange data. Many people asked me why I haven't built TWC into a XPR library. This is not possible with the current standard, and I fear this won't change. If you like to use TWC from external software, and you miss something necessary in TWC that would enable you to do so, please ask me. You can reach me via email in UseNet under lkv@mania.robin.de Good luck, Lutz Vieweg @endnode @node Version "Version history" 3.22 Some older versions of commodities.library are buggy - this lead to crashes when hotkeys where used. Applied a workaround. For the same reason I had to change the default hotkey-descriptions. Some older versions of commodities.library do not understand "NUMPAD". New defaults are F10 and F9 3.21 Default screen-mode changed to interlace The default screen-to-front hotkey description was invalid, changed to NUMPAD / Some people don't like to read what is written in gadgets, so they asked me to arrange the OK and CANCEL gadgets in the requesters in a specific order. Done: OK is now left, CANCEL right. 3.20 Many changes, improved GUI, first sound-support routines, bug-fixes, better guide, ARexx-Port, ability to use externally opened devices etc., too much changes for a detailed description here. Please take a look at the whole guide... Sound support and dial-function not ready, yet. (changed version numbering back to the old style X.YZ, this is less misunderstandable) 101 Cosmetic corrections, functions now available via menues and command-keys 100 First public release. How long will it take until the first bug is found the beta-tests did not show? @endnode @node Future "Ideas for possible future extensions of TWC" - Sound-support and the dial-function will be completed - Less linguisitc mistakes in the documentation (english is not my native language). - Improved BBS-software Interface - Video-support (this is meant seriously) - remote command exectution - maybe a screen-mode requester... :) @endnode