WinRSH - Remote Shell for Windows 1.6
WinRSH32 - 32-bit Remote Shell for Windows 1.6
Written by William Cheung (wcheung@ee.ubc.ca)
Copyright (C) 1994 William K. W. Cheung
All Rights Reserved.

WinRSH/WinRSH32 is free software; you can redistribute it in its entirety 
in any form you like.  If you find any bugs, feel free to send me an 
email at wcheung@ee.ubc.ca.  Please read "license.txt" for GNU licensing 
information.  If you have added new features to WinRSH, please send me
all the source code modifications, including the version of WinRSH that
you are based on.  Your additions may benefit other users.

Disclaimer
==========

WinRSH is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

Good data processing procedure dictates that any program be
thoroughly tested with non-critical data before relying on it.
The user must assume the entire risk of using the program.
THE AUTHOR SHALL NOT BE HELD LIABLE FOR ANY 
KIND OF DAMAGES OR CLAIMS THAT DIRECTLY OR INDIRECTLY RESULT FROM 
USING THIS SOFTWARE.

Requirements
============

o An IBM-PC or compatible computer using 386 or above CPU with at
  least 4 MB RAM.
o Window Socket installed properly.
o A host supporting at least one of RSH or REXEC daemon.

Installation
============

This package contains the following files:

ctl3dv2.dll
ctl3d32.dll
winrsh.exe
winrsh32.exe
readme.txt
license.txt
xterm
src/         <== contains the source code for WinRSH/WinRSH32 and
                 Borland 4.0 ide file for WinRSH and WinRSH32

1) Unzip wrsh16.zip using "pkunzip -d wrsh16.zip".  A directory "winrsh"
   will be created.

2) In your autoexec.bat, add the following statement:

   set rshhost_dir=c:\winsock

   where "c:\winsock" is a directory that contains your host database
   file.  This file is usually called "hosts", but for Microsoft's
   Winsock implementation, this file is named "hosts.sam".  You must
   copy it to have the name "hosts",  If you do not have such a file
   because your machine relies completely on a domain name server (DNS),
   you can ignore this part.  The main purpose of this part is to allow
   the user to select some known hosts from a range of hosts.

3) For WinRSH:
   Move ctl3dv2.dll into your Windows system installation directory, e.g.
   c:\windows\system.  This ctl3dv2.dll should only exist in your 
   Windows system installation directory on your machine or the module 
   will complain about improper installation.

   For WinRSH32:
   Move ctl3d32.dll into your Windows system installation directory, e.g.
   c:\windows\system.  This ctl3d32.dll should only exist in your 
   Windows system installation directory on your machine or the module 
   will complain about improper installation.

4) Include WinRSH/WinRSH32 in a group in the Program Manager.  Double-click
   on the WinRSH icon and there you go.

What's New
==========

WinRSH 1.6:

1. Added a message bar to display messages internal to WinRSH.

2. Fixed occasional screen garbling bugs.

3. Disconnection from the remote host is now more responsive.

4. Fixed a bug in not able to check the "Log to File" menu once it
   is unchecked.

5. The source code is now distributed as part of WinRSH in the SRC
   directory under the GNU licenses and agreements.

WinRSH 1.5:

1. Added support for including local host's name as part of the remote
   command.  This is useful for system administrators who want to setup
   a single X-Windows (requires an X-Windows server running under Windows)
   login script for all PCs in a network or for those users whose internet
   addresses are assigned dynamically.  Before using this feature, please 
   carefully read the Remote commands section in this file for further 
   information.

2. Response file command line support for long parameters.  Please read 
   Response File section for further information.

WinRSH 1.4:

1. 32-bit support for WinRSH

2. Added a "-t" option to force the connection to close when the remote
   operation does not respond within a specified number of seconds.

3. For remote commands that do not return anything, WinRSH now disconnects
   gracefully.

4. Fixed a bug in storing previously used commands in the list.

WinRSH 1.3:

1. Multiple WinRSH sessions can be executed simultaneously.

2. When WinRSH is retrieving data from the network, the system will not
   appear "hang".

3. When WinRSH finishes, it will force the remote connection to close.

4. When an internet address is specified in the host name box, connection
   will be established as opposed to the previous version in which only
   the "connecting to xxx ..." is shown.

WinRSH 1.2:

1. Added the following command line options:
   -i - minimize WinRSH window upon start up
   -q - quiet mode - WinRSH will exit when the specified command is done
   -p - password - WinRSH will switch to REXEC if this option is used
   -o - output file name

2. The remote command input box is now changed to a dropped-down list
   where the most recently used commands are listed first.

WinRSH 1.11:

1. Fixed a command line bug.

2. Allow a remote command when inputting through the command line to 
   have arguments.

3. If the required options are not fully completed, connection is not
   established automatically.

4. The protocol automatically switches to RSH if all command line options
   are specified.

WinRSH 1.1:

1. Added "Save settings" option so that the same settings can be used
   every time WinRSH is executed.

2. Added optional command line arguments.  The usage of WinRSH is:

   winrsh [-l username] [-h hostname] [command]

   (The [] means the entry is optional.)

3. Added Output logging capability.  The output can be logged to a file.

4. Added Microsoft's 3D looking.

5. Upon starting WinRSH, the connection dialog box is automatically
   displayed.

WinRSH 1.0: 
First public release

User Manual
===========

Because WinRSH is a very simple program, a comprehensive manual is
not really needed.  Upon starting the program up, you will see three
menus.  Each menu is described below:

File Menu -> Connect...

  Establish a remote connection by filling in some remote host 
  information and the remote command to be executed.  You can select 
  either the RSH (Remote Shell) or REXEC (Remote EXEC) protocol.  The 
  difference between the protocol is that the latter one requires a 
  password and the former one does not.  When you press the connect 
  button, you will execute the command in your remote host.  After a 
  remote command is done, the remote host will be disconnected 
  automatically.

  For the remote command, you can either select a command from a list of
  commands that you have used previously, or enter a different one in
  the text box.  Currently, there is a maximum of 20 commands that you
  can store in the list.

File Menu -> Disconnect

  Use this option if you want to abort a connection for any reasons.

File Menu -> Open Log File

  Open the log file for viewing/editing.  This option requires that
  notepad.exe is in your search path.

File Menu -> Select Log File

  Allows the user to specify a default log file.  The default log file
  is "winrsh.log" which is located in your Windows installation directory.

Edit Menu -> Clear

  This option clears the screen.  Note: WinRSH can buffer up to
  a maximum of 200 lines.

Edit Menu -> Save Settings on Exit

  Save the current login information (except the password) for a later
  session.

Edit Menu -> Log Output

  Turns on/off the output logging capability of WinRSH.

Help Menu -> About

  This option displays information about WinRSH.

Command line usage
==================

The available command line options are:

-l username    - a valid user name on the remote host
-h hostname    - a valid remote host name
-o filename    - an output file name for the output of the command.
-p password    - a valid password for the user name.  WinRSH will use
                 REXEC protocol if this option is specified instead of the
                 default RSH protocol.
-t seconds     - specify the number of seconds WinRSH will wait before
                 forcing the connection to close.  A value of zero means
                 infinite waiting (default).
-i             - WinRSH minimizes itself if this option is specified.
-q             - WinRSH terminates itself when all data are received from
                 the remote side.
@response_file - name of a response file.  Please read the Response File
                 section for further information on the syntax of a response
                 file.
command        - a valid command.  If the command contains arguments,
                 a pair of double quotes (") should be put around the whole
                 command, e.g. to connect to host "unixhost" with user 
                 name "root" and remote command "ps ux", the required
                 command line should be

                 winrsh -l root -h hostname "ps ux"

                 Please note that some command line processor will strip
                 the double quote upon passing the arguments to WinRSH.  To
                 get around with this, use \" instead of ".

To run WinRSH transparently, you can use options -i, -q and -o together.
For example,

winrsh -l root -h hostname -i -q -o output.txt "ps ux"

To run more than one command on the remote side, you can use a shell on
your remote host that accepts multiple commands on a single command line
such as "csh" or "tcsh".  Then, when using winrsh, use ";" to separate
the commands.  For example, to run "ps ux" followed by "ls", 

winrsh -l root -h hostname -i -q -o output.txt "ps ux; ls"

Remote Commands
===============

Currently, WinRSH does not support remote commands that require user
interaction, i.e. user input for invoking the command.  To use WinRSH
to start up X-Terminals or other X-Windows applications, you must have
an X-Windows server (such as Hammingbird eXceed or StarNet's MicroX) 
already running under MS Windows.

A remote command can contain any characters.  To include your local host
name as part of the remote command, use "$i" without the quotes.  If the
"$" sign must appear in the command, you must use "$$" instead.  For
example, if you want to send "$" or "$i" to the remote shell, you must
use "$$" or "$$i" instead.  Please note that use of the "$i" option may
not work with your Winsock implementation especially when the internet
address is assigned dynamically.  For instance, it works under Trumpet 
Winsock 2.0A but it does not work under Chameleon's Sampler (can only
assign a host IP-address dynamically but not the host name dynamically).
Users of TIA (The Internet Adaptor) should keep in mind that the suggested
IP address (192.0.2.1) may not work on your site if that IP address is not
mapped to a host name

To run more than one command on the remote side, you can use a login shell 
on your remote host that accepts multiple commands on a single command line 
such as "csh" or "tcsh".  Multiple commands are separated by a ";".  The 
maximum allowable length of a command line is 255 characters.

WinRSH does not disconnect immediately even when you include a "&" at the
end of the remote command.  However, when the child process is done, WinRSH
will terminate gracefully.  One way to circumvent this is to use the "-t"
option in the command line to set up a termination time.

The following are some examples for system administrators or home users who
want to start up an X-Terminals using WinRSH, assuming that an X-Windows
server is already running on your PC:

winrsh -l wcheung -h datacom -q -i -t 30 "xterm -ls display $i:0.0 &"
winrsh -l wcheung -h datacom -q -i -t 30 "setenv XAPPLRESDIR $$HOME/lib/app-defaults; xterm -ls display $i:0.0 &"


Response File
=============

A response file contains a list of command line arguments to be passed to
WinRSH.  This is useful when the command line arguments' length is greater
than 128 characters.  The syntax of a response file is very simple - One
command per line.  All command line options listed in Command Line
Usage section can be used.  For options -l, -h, and -p, the arguments are
optional.  Using the -p option (without arguments) tells WinRSH to use
REXEC protocol instead or RSH protocol.  This allows a system's 
administrator to allow a user to input the values before connection occurs.  
An example response file, xterm, is included in the distribution.  To use 
this response file, simply enter "winrsh @xterm" in a command line.

Note: If you use a response file, do not use other command line options in
      a command line.

