UW/WIN Version 1.03 Russell Poffenberger January 1992 INTRODUCTION This document describes version 1.03 of UW/WIN. This application is designed to run on IBM-PC's and compatible computers under Windows 3.0. This program was inspired by UW/PC, written by Rhys Weatherley. This program is entirely independent from UW/PC, and bears no resemblance to UW/PC other than its basic functionality. UW in general is based on a program written for the Macintosh by John Bruner. It provides for up to seven separate sessions on a remote UNIX machine. A UW server package must be running on the UNIX system for any of the advanced features to work. IMPORTANT NOTE In order to be less "similar" to UW/PC, some of the UW commands have been changed. Particularly the "New" command (Alt-N, creates a new UW session and window) has been changed to "Create" (Alt-C), "Kill" (Alt-K, kills the current window) has been changed to "Remove" (Alt-R), and "Exit" (Alt-E, exits the UW protocol) has been changed to "Protocol 0" (Alt-0). Also, "Upload" and "Download" (not implemented yet) have been changed to the "Page Up" and "Page Down" keys respectively. Version 1.03 is the second version released to the public so far, and comments are welcome. This version implements the Unix Windows protocols 0 and 1. The UW server also has a "protocol 2" available, but is not yet implemented. Protocol 2 provides more window management. Look for support in a future release. Note that the documentation for the server states that it will probably not compile on anything but BSD based UNIX systems. It will not work on System V. Also, UW/WIN will not operate in REAL mode. This is because Borland C++ is used, and BC++ does not support making REAL mode applications. At such time that Borland supports this, or Microsoft supports this in a C++ compiler, I will likely provide REAL mode support. UW/WIN is distributed in the hopes that it will be found useful. If you like the program, a contribution to the author of $20 (or whatever you feel it is worth) would be appreciated and will help to keep enhancements and future products available. With any contribution, you will receive notification of new versions. With any contribution of $10 or more, you will receive a bound manual. Feel free to distribute this program as you wish, so long as its contents, and this notice are not changed. Note, however, that the server is copyrighted by John Bruner, and is not covered under these terms, and has its own terms and conditions contained within its documentation. For that reason, the server is not bundled with this package, but must be obtained separately. The source code for the server, packaged together with the Macintosh binaries can be downloaded from some ftp sites. The standard distribution is available in the directory "mirrors/unix-c/macintosh" on "wuarchive.wustl.edu" [128.252.135.4]. The file is named "uw42.tar-z". On "cica.cica.indiana.edu" [129.79.20.22] as uwserver.zip (no MAC binaries) in the "pub/pc/win3/util" directory. The DOS based PC version can be obtained from "wuarchive.wustl.edu" in the mirrors/msdos/modem directory. Comments about UW/WIN can be sent to the author at one of the following addresses: Internet: poffen@sj.ate.slb.com UUCP : {uunet,decwrl,amdahl}!sjsca4!poffen CIS : 72401,276 US mail : Russ Poffenberger 2827 Old Estates Ct. San Jose, Ca. 95135 Comments about UW/PC (the DOS version), can be sent to: Rhys Weatherley -- rhys@cs.uq.oz.au Comments about the UW server for UNIX hosts should be sent to John Bruner: ARPANET/MILNET: jdb@mordor.s1.gov UUCP: {lll-crg,decwrl,caip}!mordor!jdb U.S. Mail: John Bruner Lawrence Livermore National Laboratory P.O. Box 5503, L-276 Livermore, CA 94550 FILES The following files should be present in the UW/WIN archive: UWWIN.EXE The actual UW/WIN Windows 3.0 executable. UWWIN.DOC This documentation file. DEFAULT.UW An example configuration file. README.UWW History of UW/WIN versions. UWWIN.HLP A Windows 3.0 compatible help file. USING UW/WIN When UW/WIN starts, it creates a client area, then brings up the "File | Open" dialog box, allowing you to select a configuration file. You may select one of the available files, or press "Cancel". Pressing "Cancel" will NOT initialize the serial port or parameters. Use the various menus and dialog boxes (described below) to setup the desired parameters. You may navigate the drives and directories to find configuration files. By default, the directory where the UW/WIN executable was executed from is the starting directory. You may specify the name of a configuration file on the command line. In this case the opening dialog is skipped, and the configuration file is read in directly. This allows you to setup filemanager associations, or create an icon in a program manager group to represent a specific connection. Once you have selected a valid configuration file, or picked a com port for use from the "Setup | Comm" menu, UW/WIN enters "Protocol 0", which is equivalent to the dumb terminal emulations available in conventional communications programs. The default emulation is ADM31, but VT52 emulation is also available. A number of special keystrokes are defined in protocol 0: ALT-B - Sends a line break over the serial link. ALT-I - Send the modem initialization string. ALT-U - Send the string defined by the "uw" initialization setup. This is useful once connected to start the UW server on the UNIX host. See "CONFIGURING UW/WIN" below. ALT-Q - Quit the program: All windows will be destroyed, and UW/WIN will be exited. You will be prompted before quitting. These functions may also be invoked under the "UW" menu. The purpose of protocol 0 is to allow you to connect to the UNIX host in in the normal fashion. When you are ready to use the multiple-window mode of UW/WIN, execute the UW server on the remote host by typing its command name, or by pressing ALT-U if the "uw" command string has been set correctly (see below). Note that the server must be compiled and accessible for you to do this. When the server starts, it uses special characters to begin the protocol with UW/WIN. The current window now becomes UW window 1. At this point, up to six more login windows may be started, either by using the ALT-N key, or using the "UW" menu. At this point, ALT-U, or the corresponding menu have no effect, and the following commands (or menu equivalents) are available : ALT-0 - Exit the UW protocol. If any windows are present, they will be terminated. You will be prompted for verification first. This function does NOT hangup the modem before exiting, so UW/WIN can be restarted. ALT-R - Remove just the current window. ALT-C - Create a new window. Up to 7 windows total may be created, if all 7 windows are already up, then this has no effect. ALT-n - "n" is a digit between 1 and 7. Make window 'n' the active window. It will be brought to the top, and given keyboard focus. Usually, if you exit a UNIX shell in a window, that window will be killed automatically, if you exit window 1, then ALL other windows will be killed, and UW/WIN will return to protocol 0. Each window contains a status bar at the top. This bar contains information about the window, such as the window number, the screen size (columns X rows), and which protocol is in force. The screen size is useful to set the UNIX terminal characteristics correctly (usually using stty, refer to your UNIX system documentation for specific information.) after changing the window size. When a window is iconified, the window name is shortened to indicate just the window number, so as not to clutter up your windows desktop. The UW server usually defaults to using ADM31 emulation whenever it creates a new window. You may need to manually modify the UNIX terminal type in the windows to get the correct screen behavior if you have set your default emulation type to something other than ADM31 in the configuration file. If you are using the Bourne shell compatible shell, you can add the following lines to your ".cshrc" file to automatically change the terminal type to SS, where SS is your preferred terminal type. case $TERM in adm31) eval `tset -s SS`;; *) ;; esac When the UW server starts, it will set the TERMCAP environment variable within a UW window, but in protocol 0 the TERMCAP environment is not set automatically. The following TERMCAP string may be used if your system lacks a working adm31 entry. You may create an entry in your termcap file, or set your environment to this string. The formatting is for looks only, delete all leading and trailing spaces and returns to make it a single string if setting it in the TERMCAP variable. If adding to the termcap file, escape the end of each line with a backslash '\'. adm31:cr=^M:do=^J:nl=^J:al=\EE:am:le=^H:bs:ce=\ET: cm=\E=%+ %+ :cl=^Z:cd=\EY:co#80:dc=\EW:dl=\ER: ei=\Er:ho=^^:im=\Eq:li#24:mi:nd=^L:up=^K:MT:km:so=\EG1:se=\EG0: UW/WIN allows for two different emulations to be used automatically. You may set the protocol 0 emulation (through the Emulation... dialog) to be something simple, typically vt52, since most UNIX systems have this entry. When entering protocol 1, the protocol 1 emulation will automatically be used. CONFIGURING UW/WIN When UW/WIN starts up, it first pops up a dialog box allowing you to select an existing configuration (profile) file. This file conforms to standard Windows 3.0 ".ini" conventions. If you press "Cancel", then no setups will occur, and you must use the various setup menus and dialog boxes to configure the various parameters. Once you have the desired settings, you may save this to a named profile file. An example configuration file is distributed with UW/WIN. Each line of the file is of the form "name=arg" where "name" is the name of the configurable parameter, and "arg" is its argument. Comments may be introduced starting with "#", but may not appear within commands. The configurable parameters, which are all optional, and their defaults follow: comport The serial port to be used for communications. This can be either 1, 2, 3, or 4. baudrate The baud rate to use for transmission. This can be one of 300, 600, 1200, 2400, 4800, 9600 or 19200. parity The parity to use for transmission. This can be one of none, even or odd. datasize The number of data bits (7 or 8) to use for transmission. stopbits The number of stop bits (1 or 2) to use for transmission. modeminit The modem initialization string, The string cannot be longer than 128 characters in length. p0emulation The default terminal emulation type to use for protocol 0. This is to rectify some problems with UNIX termcap entries that are missing the entry for ADM31 terminals, as discussed above under "USING UW/WIN". It can be either adm31 or vt52. p1emulation Set the terminal emulation type for protocol 1. This is is the emulation used under protocol 1. This can be either adm31 or vt52. flowcontrol Specifies which type of flowcontrol to use. It can be either hardware or software. dialprefix This string is sent to the modem when dialing. phonenumber This string contains the phone number to send to the modem when dialing. It is appended to the dialprefix string. f1_key - f10_key These ten configuration variables allow you to define the function keys to any strings you desire. If you do not define a function key, it will have its default setting as defined by the terminal emulation in use. The characters "^" is used to indicate that the next character is a control character, ie "^m" is carriage return. The string should be 128 characters or less. uwcommand This specifies the string to send in response to ALT-u, or when selecting "Start UW" from the "UW" menu. The "^" character is treated as described above. fontresources This specifies the name of a file (or files) to load for extra fonts. Usually these are ".fon" files. You can specify more than one by separating the file names with a space. This cannot be changed at runtime. historylines This specifies the number of lines for the scrollback history buffer. This cannot be changed at runtime. bskey_map If non-zero (true), then the backspace key will output the "del" code (0x7f). redialdelay This value specifies the delay (in seconds) before attempting a redial if the previous dial was unsuccessful in connecting. Most of these options may be changed at runtime using the various menus and dialog boxes. Any changes made affect only the current session. You may save these settings to a profile file by choosing the "File | Save" or "File | Save As" menu item. The menu operations are described below. File This menu item contains a submenu consisting of the following items. Open Provide a dialog box to allow selection of s profile file to load. Save Save the current settings to the profile file last loaded. If no file has been loaded, the this will invoke the "Save As" function explained below. Save As Pop up a dialog box allowing the user to select an existing file, or enter a new one to save the current settings to. The extension ".uw" is recommended. Exit Exit UW/WIN. Edit This is the interface to the clipboard. Copy If there is selected text, then this menu is enabled. Selecting it will copy the selected text to the Windows clipboard. Paste If there is compatible text in the clipboard, then selecting this function will copy the text from the clipboard to the window session, sending it to the remote system. Copy then Paste This will perform a copy and subsequent paste in a single operation. Setup From this menu you can invoke either the "Comm", "Initialization", or "Emulation" dialog boxes. Comm Use this dialog box to set the various communication parameters, such as baud rate, parity, etc. Initialization This dialog box allows you to specify strings to use for the dialing prefix, modem initialization, and the UW command. Emulation Use this dialog box to select which emulation to use for each protocol. Help This version of UW/WIN contains a Windows 3.0 compatible help file. The items under this menu can be used to index into help file using the Windows 3.0 help facility. An "About" box provides version and identification information. Dial The "Dial" menu provides two entries, "Number" and "Hangup". Number This brings up a dialog box allowing you to edit the number to dial, and to invoke dialing. Pressing "Cancel" before connection has occurred, will terminate the call in progress. Hangup Selecting this will cause a hangup using the Hayes standard escape sequence "+++" to gain control of the modem, then issuing "ath0" to hangup the modem. This will not gracefully exit the UW protocol, and should only be used in an emergency. Keys | Function This menu, when selected, will bring up a dialog box allowing you to program your own strings to function keys. The dialog provides ten radio buttons to select which function key to program. The edit box show the current string, and allows you to edit the string. Once the string is the way you want it, press "Save" to save the string. If you don't save it, it will be lost. At this point, you may select another function key to program, or exit the dialog box. Strings should be 128 characters or less. Keys | Mapping This dialog allows you to select various default key mappings. Currently, the only mapping supported is to map the Backspace key to the Delete code (0x7f). Checking the box enables the mapping, unchecking the box disables the mapping. UW Refer to the UW commands description above. Help From this menu, you may index into the help file using the Windows help facility. Fonts Yoy may select which font you wish to use in the terminal windows. The menu is created dynamically based on available fixed pitch fonts available at the time UW/WIN was started. Even fonts available via ATM may be used. Note that only fixed pitch fonts will be shown, and be careful with very small fonts. If the font is so small that the system menu takes more than one line, then some problems will occur. This will hopefully be fixed in a future release (it is a difficult problem). There is also a menu entry "Bold". Selecting this will toggle bold on/off. When a checkmark is next to it, then the characters will be in bold. On startup, UW/WIN uses the default SYSTEM font, and sets the window to 80 X 24 lines. You may resize the window by dragging a border, just like any other Windows application. Read the "Microsoft Windows 3.0 Users Guide" for more info. The standard system colors "WINDOW" and "WINDOW_TEXT" are used for the client area background and text respectively. These can be changed using the "Color" utility in the Windows "Control Panel" program manager group. LIMITATIONS There are some limitations in UW/WIN and the UW server. If a lot of data is being received in one window, the UW server will be slow to process input from another. This is caused by the server, not UW/WIN. Another problem is one of modem communication reliability. Unless an error correcting modem protocol is used, characters could be dropped, lost or garbled. If one of the protocol bytes gets affected, strange behavior may result, such as output going to the wrong window, or input from one window going to the wrong session. If things become entirely out of sync, try exiting the UW protocol. If this doesn't work, try "ctrl-A" followed by the "Delete" key. The UW commands are a small part of the total data (statistically speaking) so these problems should be uncommon. Using an error correcting modem or protocol such as V.42, MNP 4, or Telebit PEP will avoid these problems. When using such modems, it is highly recommended that you make use of hardware flow control. Since high speed error correcting modems implement their own modem to modem flow control, it is much more efficient to let hardware handshaking govern the flow of characters. Some high speed protocols, particularly Telebit's PEP, don't switch the send/receive lines too well when a large amount of traffic is going in one direction. Attempting to use software flow control (where an XOFF character is sent to the remote system to turn off output) will generally result in lost characters. For low speed (2400 and below), the modems have no internal flow control mechanism, so you must use software flow control. There is also a bug in Windows 3.0 related to the comm ports. If you type while any window is busy receiving and displaying data, the data you type may get "stuck" in the send queue. If this appears to happen, wait till the receive activity is through, and type another key, this will unstick the queue and send all queued characters. FUTURE WORK In the future, UW/WIN will be extended with the following capabilities: ANSI terminal emulation, X/Y/Zmodem file transfers in any window (and also protocol 0), and support for a subset of the UW protocol 2 features which gives more control over window management. Other minor features may include saving of selected font information to the configuration file, and other convenience items. Comments and suggestions are very welcome.