Category : UNIX Files
Archive   : UWWIN102.ZIP
Filename : UW.DOC

UW/WIN Version 1.02

Russell Poffenberger

November 1991

1. INTRODUCTION

This is version 1.02 of UW/WIN, a multiple-window interface to UNIX for
IBM-PC's and compatible computers running Windows 3.0. This program is based
on a program written for the Macintosh by John Bruner. It provides up to seven
separate login sessions on the remote UNIX machine, and requires the
UW server to be running on the UNIX host. Before UW/WIN can be used in
a multiple session mode, the server must be compiled and installed on
the UNIX machine.

The source code for the server, together with the Macintosh program
binaries can be found on many ftp archive sites. The standard server
distribution is available in the directory "info-mac/unix" on
"sumex-aim.standford.edu" [36.44.0.6]. The files are named
"uw-42-part1.shar" ... "uw-42-part8.shar". On cica.cica.indiana.edu
[129.79.20.22] as uwserver.zip.

Version 1.02 is the first public release, and comments are invited to the
author. It implements the Unix Windows protocols 0 and 1. Protocol 2 (with
more control over window management) was not implemented at this time because
of time constraints. This support is being worked on. Look for it in a future
release.

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 is not changed. Note however that the server
is NOT covered under this license and comes under the terms and conditions
contained within its documentation.

Comments about UW/WIN can be sent to the author at one of the following
addresses:

Internet: [email protected]

UUCP : {uunet,decwrl,amdahl}!sjsca4!poffen

CIS : 72401,276

US mail : Russ Poffenberger
2827 Old Estates Ct.
San Jose, Ca. 95135


Comments about the UW server for UNIX hosts should be sent to John Bruner:

ARPANET/MILNET: [email protected]

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

2. FILES

The following files should be present in the UW/PC distribution:

UWWIN.EXE The actual UW/WIN Windows 3.0 executable.
UW.DOC This documentation file.
DEFAULT.UW An example configuration file.
README.UW History of UW/WIN versions.
UWWIN.HLP A Windows 3.0 compatible help file.

The Macintosh binaries have been stripped from the server, and can be
obtained from one of the FTP sites mentioned above if desired.

3. 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.

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 - Send a line break over the serial link. CTRL-BREAK and
CTRL-END will also send a line break.
ALT-D - Send the string defined by the "dial" configuration
variable to the modem. See "CONFIGURING UW/PC" below.
ALT-H - Hangup the modem, by first dropping the DTR signal,
and then sending the hangup string if the carrier
signal is still present.
ALT-I - Send the modem initialisation string, even if a
carrier signal is present.
ALT-R - Receive an ASCII file from the remote host. You will
be prompted for a filename to place the data in. When
the data has been transferred, press ESC to abort the
transfer.
ALT-S - Send the contents of an ASCII file to the remote host.
Lines will be terminated with carriage-return characters
only, and there is a 0.1 second pause between lines
to allow the remote host some time to "catch-up". You
will be prompted for the filename to transfer. Press
ESC to abort the transfer at any time.
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-X - Exit the program. If any windows are present, they
will be destroyed. This function does NOT hangup
the modem before exiting, so UW/WIN can be restarted
in protocol 0 if required.
ALT-Q - Quit the program: All windows will be destroyed, and UW/WIN
will be exited.

These functions may also be invoked under the "UW" menu.

Protocol 0 exists to allow you to connect to the UNIX host in whatever
way the host requires. When you are ready to use the multi-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" configuration variable has been
set correctly (see below). Note that the server must be compiled and
accessible for you to do this.

The UW server sends a special control sequence which UW/WIN interprets
and automatically starts the multi-window session. By default the
server will also create a terminal window. See the documentation that
accompanies the server for information on modifying its behaviour. Once
UW/WIN has entered the multi-window session (protocol 1), up to 7 windows
are available, ALT-U no longer has any effect, and the following
additional special keystrokes are defined:

ALT-E - Exit the UW session and return to protocol 0.
A "kill window" request will be sent for all currently
active windows.
ALT-K - Kill the current window.
ALT-N - Create a new window if possible. Up to 7 windows
may be created and used.
ALT-n - "n" is a digit between 1 and 7. These keystrokes
direct UW/WIN to "jump" to the nominated window.

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 behaviour if you have set your default
emulation type to something other than ADM31 in the configuration file.
If you are using the Korn shell "ksh", you can add the following lines to
your ".kshrc" file to automatically change the terminal type to XXX, where
XXX is your preferred terminal type.

case $TERM in
adm31) TERM=XXX export TERM ;;
*) ;;
esac

Some UNIX termcap entries do not have the entry for the ADM31 terminal type,
and so some UNIX programs may not have the correct screen behaviour. The
UW server will set the TERMCAP environment variable within a UW session
window, but in protocol 0 this environment variable is not set automatically.
To use ADM31 emulation in protocol 0 on machines without the correct termcap
entry, set the TERMCAP environment variable to the following string (newlines
and spaces are for layout only, and shouldn't appear in the actual value):

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:

Alternatively, setting the "emul0" configuration variable to "vt52" will
allow you to use VT52 emulation in protocol 0, which is usually defined
in all termcap and terminfo entries. ADM31 emulation will still be used
for UW session windows if the "emul" variable is set to "adm31". ADM31
emulation is much "smarter" than VT52, so you will probably want to use
it wherever possible.

All of the special protocol 0 keystrokes except ALT-U also work in protocol
1, but it is inadvisable to use ALT-I during a UW session. ALT-H will still
hangup the modem, after exiting the UW session. ALT-B will first exit
any active UW session before sending the BREAK pulse. This avoids some
strange things that may occur with network terminal servers and the like.
ALT-X will also terminate a UW session before exiting UW/PC.

4. USING UW/WIN WITH OTHER PROGRAMS

UW/WIN can be used as a stand-alone communciations program, or in
conjunction with some other communciations program. If you have a
favorite communications program (e.g. Telix, Procomm, MS-Kermit, etc),
and have extensive "scripts", etc to connect you to a UNIX host, and
still want to use these functions, you can still do so. Once connected
to the UNIX host (or whenever you are ready), you can shell out to a DOS
shell (a function available in most programs), and execute UW/PC to
handle the UW sessions. Note that you must execute the UW server from
within the control of UW/PC otherwise the startup control sequence that
the server sends to UW/PC may be missed. You can exit UW/PC at any time to
return to the other program. It may also be possible for your program's
scripting language to automatically execute the UW/PC program once a
UNIX host connection has been made.

5. 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.

All 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.

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.

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).

On startup, UW/WIN uses the defaults SYSTEM font, and sets the window to
80 X 25 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.

6. LIMITATIONS

UW/WIN and the UW server have a number of limitations. Primarily, if
a large amount of output is appearing in one window, the UW server will
be slow to process input and output in another. This is a limitation
of the UW server, and not UW/WIN. The second limitation is unavoidable.
With all serial communciations over telephone and other serial links,
errors in transmission are likely to occur. The UW protocols have no
provision for error-free transmission of information, and especially
the special UW commands that are sent back and forth between UW/WIN and
the UW server are not sent using an error-free transmission. If errors
occur in the transmission of these commands, strange things like output
appearing in the wrong windows may result. Since the UW commands are
fairly rare (usually only when swapping windows for input or output), and
the chances of normal data being corrupted into legal UW commands are
very small, very few problems should result on reasonably clean modem
connections. As a last resort, you can press ALT-E to return to protocol
0, and if the UW server hasn't exited (because the exit command was
corrupted), you can press (while in protocol 0, not protocol 1) "CTRL-A"
followed by the "Delete" key, which corresponds to the UW exit command,
which should abort the UW server. 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.

7. FUTURE WORK

In 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. Comments and suggestions are very
welcome.