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.