------------------------------------------------------------------------------

		  OS/2 2.0 SLIP Driver for IBM TCP/IP v1.2.1

		      Version 1.0 (Beta) - April 12, 1993
			  David Bolen - db3l@ans.net

				    README

------------------------------------------------------------------------------

This file describes the contents of the SLIP20B1.ZIP archive, and presents a
brief description of how to install the SLIP driver and get everything up and
running.

This file contains the following sections:

	Driver History		Release history for SLIP Driver
	Archive Contents	Description of the contents of the archive
	Installation		Basic Installation Instructions
	Getting Connected	Establishing the SLIP connection
	Attach scripts		Using Rexx scripts to make a connection
	Executables		Brief usage descriptions of executables
	Reporting Problems	What procedure to follow to report problems
	Administrivia		E-Mail addresses


+----------------+
| Driver History |
+----------------+

This is the first beta release of the OS/2 2.0 SLIP Driver:

	Beta-1		April 12, 1993
	------

	Well, the alpha code turned out to be available for much longer and
	more widely distributed than I had originally intended.  This release
	is mostly a recognition of the fact that the code has already been
	effectively tested as beta code.  It should be a short beta.  Note
	that I did perform an internal code clean-up on the whole package, 
	and there are a few externally-visible changes:
		- All alpha/debugging output has been suppressed by
		  default.  A commmad line option of "-d" will re-enable
		  all debugging messages as before.
		- A comma can now optionally be used in the slip.cfg
		  configuration file to separate elements.
		- The Rexx script functions com_input and com_output have
		  been renamed to slip_com_input and slip_com_output.
		- The return code from Rexx scripts now determines if the
		  driver exits.  A zero return code indicates success while
		  a non-zero value indicates failure.
        The last two items above represent differences that will require
	changes to any scripts that may have been written.  If you are using
	the supplied slipup.cmd script, you can just use the new version
	from this package.


	Alpha-3		October 28, 1992
	-------

	After a bit of a hiatus, I've added much of the functionality that
	I want to go to beta with.  The big two user-visible items are a new
	configuration file, and the support for calling a Rexx script to 
	handle establishing the SLIP connection.  Internally, the core 
	forwarding path has not changed, but a number of improvements have
	been made to simplify handling multiple interfaces in the next update.
	

	Alpha-2		September 24, 1992
	-------

	This was a release solely of the SLIP Driver executable.  The new
	executable contained a fix for the bug encountered when large packets
	were received by the driver that exceeded the interface mtu.


	Alpha-1		September 21 & 23, 1992
	-------

	This was the first public release of the OS/2 2.0 SLIP Driver code.
	The original release on 9/21 was augmented by a release of debugging
	versions of the driver on 9/23 to aid in problem reporting.


+------------------+
| Archive Contents |
+------------------+


The SLIP20B1.ZIP archive contains the following files:

	readme		This file

	slip.exe	Main SLIP Driver
	slipwait.exe	Utility to wait until SLIP is up and running
	slipterm.exe	Simple terminal program for making SLIP connections
	sliphold.exe	Utility to hold a COM port open
	sldetach.exe	Utility for forceably detaching a SLIP interface
	slcfg.exe	Utility to test parsing SLIP configuration files

	slip.cfg	Sample SLIP configuration file (store in ETC directory)
	slipup.cmd	Sample SLIP attach script (keep somewhere in path)

	ifndisnl.sys	"Null" version of ifndis.sys.  This can be used in
			place of the standard ifndis.sys if you are only using
			the SLIP interface (no LAN interfaces)


+--------------+
| Installation |
+--------------+

NOTE: In order to be able to use this SLIP driver, you must be running
      OS/2 2.0, and you must have the current release of the IBM TCP/IP
      package installed (at least UB02252 or above).

      This is critical!  If you have an earlier version, depending on the
      level, SLIP may simply not run, or it may crash your system.  Or if
      it doesn't, some utilites, like "netstat" - may...

      The most common indication that you are not running an appropriate
      version is the message "Error 22 during DosDevIOCtl(SLATTACH)" during
      the startup of the SLIP driver.

      The latest CSD for TCP/IP is available from ftp-os2.nmsu.edu.



Step 1 - CONFIG.SYS
-------------------

Presuming you have used ICAT to install TCP/IP, your CONFIG.SYS should
already be pretty well set up.  However, it's not absolutely necessary to use
ICAT, and in fact if you are just copying TCP/IP off of an already installed
machine to set up a SLIP machine, it may prove easier to just do the setup
manually.

The important pieces of the puzzle are to have at least the following in your
CONFIG.SYS:
	DEVICE=\path\INET.SYS
	DEVICE=\path\IFNDIS.SYS   (or IFNDISNL.SYS - see below)
	RUN=\path\CNTRL.EXE
   where "\path" is the location where you installed the TCP/IP binaries

If you are only using the SLIP interface (ie: a home machine), besides not
requiring the protocol manager and assorted baggage, this SLIP driver does
not really even require the ifndis.sys device driver.  If you like, you can
replace ifndis.sys with the ifndisnl.sys (IFNDIS "Null") driver that is 
supplied as part of this package.  This will save both the memory involved
with ifndis.sys (all of the LAN interfaces and NDIS code), as well as
several threads and 40-50K of stack in cntrl.exe.


Step 2 - SLIP.CFG
-----------------

You must place a file called SLIP.CFG in your ETC directory (pointed to by
the ETC environment variable - normally \tcpip_root\ETC - where tcpip_root is
where you installed TCP/IP).  A sample SLIP.CFG is supplied in the archive
that describes in detail the format of the file.

For the most part, it is recommended that you start off with a default
SLIP.CFG, and then experiment if you like after you have a running system.  
However, there are two parameters that you may need to change just to get 
anything running at all:

	device		Set this to the COM device to run the SLIP
			interface over (if something other than COM1)
	compression	Set this to OFF if the far end of the SLIP link
			does not understand VJ compression.

So for an interface without compression using COM3, you would change the
supplied SLIP.CFG file interface line from:

	interface sl0 { }

to

	interface sl0 { device=com3  compression=off }

If you disable compression, you may also find that you need to increase 
your MTU size to 1006, which is the older SLIP default MTU for an uncompressed
link.  If you do not increase the MTU, you may receive messages in the SLIP
driver's window of the form:

	Warning: Received packet (###) > MTU (296)\n",


Step 3 - SLIP Executables
-------------------------

You should load the remaining SLIP executables into whatever directory you
would like, and place that directory in your PATH for easy access to the
utilities.  The sample script (SLIPUP) and any other scripts you may write
should also be located either in the directory where you start the SLIP
driver (SLIP.EXE) or somewhere along your PATH.


+-------------------+
| Getting Connected |
+-------------------+

In general the following steps are the simplest for getting a SLIP connection
up and running.  If you want to use the Rexx scripting capability for
automating this process, see the next section.

1. Configure your COM port appropriate for baud/parity, etc..  For example,
	mode com1: 38400,n,8,1,buffer=auto,rts=hs
   (Adjust the port number, baud rate, etc.. as appropriate.  If you have
    a 16550 UART, I'd strongly suggest trying buffer=on for improved
    performance)

   This can also be put in your CONFIG.SYS via a CALL= command if you like.

2. In a separate OS/2 command process (window or full-screen), start the
   SLIP driver (slip.exe).  You can also put it in its own window by
   using the "start" command (ie: "start slip").

   In theory, the SLIP driver can be run as a background driver, as CNTRL.EXE
   is, and could be started from config.sys.  However, in general (especially
   for the beta) I'd recommend leaving it in a window you can see, in case 
   diagnostic messages are displayed.

3. If you need to dial a number and perhaps log into a system to start
   SLIP, run SLIPTERM at this point.  SLIPTERM will put up a banner,
   request access to the COM port from SLIP, and then allow you to talk
   to the modem directly.  SLIPTERM is just a very simple communications
   program.  You will have to enter any dialing commands manually (ie: ATDT),
   but it will allow you to perform any operations (such as logging in
   and issuing some initial startup commands) that you may need to create
   an active SLIP link.  Press F10 (or ESC) when done.

4. Configure the SLIP interface with your SLIP address, and with the
   address of the far end.  Note: Unlike IBM's driver, my SLIP driver sets
   up serial interface "sl0", not just "sl":
	> ifconfig sl0 147.225.2.15 147.225.2.1
			  (you)      (far end)

5. If you like, add a default route through the far end:
	> route add default 147.225.2.1 1
			     (far end)

At this point you should be all up and running.

You can place all of this in a command file if you like.  If you do this,
the command file can check ERRORLEVEL after running SLIPTERM.  If it is 
non-zero, then SLIPTERM exited via ESC, while if it is 0, F10 was used.  This
can be used to control whether the SLIP interface is actually configured.

Also, if you are automating this process, you may want to use either SLIPWAIT
or the "-w" option on SLIPTERM.  SLIPWAIT takes a single numeric argument
which is the # of seconds to wait for SLIP to complete starting up (and it
defaults to 30).  This can be used to pause a command script while waiting
for SLIP.EXE to fully start up.

Specifying "-w##" to SLIPTERM will cause it to also wait for SLIP to finish
starting up.  ## specifies the number of seconds to wait, or if not given
(ie: you just use "-w") it defaults to 30 seconds.


+----------------+
| Attach Scripts |
+----------------+

One of the nicer features of this SLIP driver is the ability to use Rexx
scripts to automate the attachment of a SLIP interface.  The SLIP driver will
automatically execute an attach scripts when it starts up and is creating the
SLIP interface.  Scripts are free to use the full power of Rexx and issue
OS/2 commands as necessary.  In addition, the SLIP driver defines Rexx
functions that can be used to access the COM port that the driver is using
for the interface.


Defining a Script
-----------------

In order to use a script for an interface, you need to set the "attachcmd"
and "attachparms" parameters in the interface definition in the SLIP
configuration file SLIP.CFG.  For example, the entry:

     interface sl0 { attachcmd "slipcall" attachparms "these are parms" }

would cause SLIP to run the script "slipcall.cmd" and pass in the parameters
"sl# , these are parms".  SLIP will always pass in the name of the interface
for which the script is running as the first argument, with the attachparms
value as the second argument.

Currently this script is only run once, when SLIP starts up for the
interface.


SLIP Rexx Functions
-------------------

The following functions are available to Rexx scripts running beneath the
SLIP driver:

     slip_com_input ( interface , [ max_characters ] , [ timeout ] )

	Reads characters from an interface's COM port.  

	interface	The name of the interface (ie: sl0), and should be 
			the same as the	interface name supplied as the first 
			argument to the script.
	max_characters	The maximum number of characters to return with 
			this call.  It may return less.  The default is to
			return up to 255.
	timeout		How long to wait (in milliseconds) if no data is
			available on the port.  If this is not specifed, or
			is given as 0, it will wait forever until some data
			arrives.


     slip_com_output ( interface , string )

	Write characters to an interface's COM port.

	interface	The name of the interface (ie: sl0), and should be 
			the same as the	interface name supplied as the first 
			argument to the script.
	string		Character string to be sent to COM port.  Nothing
			is done to the string, nor is any automatic CR added,
			so you must specify exactly what characters to send.


	Note that even when this function returns to the Rexx script, not all
	of the characters may have been physically transmitted over the COM 
	port.  There are internal buffers within the SLIP driver that may 
	hold the outgoing COM data while the port is busy or disconnected.


     slip_getch ()

     	Read a character (no echo) from the keyboard

	This function simply waits for the user to press a key and returns
	that key.  It does not echo the keypress to the screen.  It is
	designed to be used for when scripts need to prompt the user for
	a password or other sensitive information.

	This function will only work if the SLIP driver is running within
	an OS/2 command session where a user may interact with the driver.
	If it is running as a detached session, this function will always
	return an empty string.


Sample Attachment Script
------------------------

The file SLIPUP.CMD in the archive is a sample script that I have used to
make a SLIP attachment through our Xylogics Annex Terminal Server.  It may
prove useful as an example on how to write such scripts for other
environments.

More detailed comments are available within the script itself, however its
basic purpose is to issue a dial command, handle the Annex logon, issue a
SLIP command, and then parse the answer to appropriately configure the sl0
interface with the right address.


Comments
--------

I'm very interested in feedback as to what sort of additional support the
SLIP driver could provide to make it easier to write Rexx scripts for this
sort of purpose.


+-------------+
| Executables |
+-------------+

slip.exe	Main SLIP Driver

   Usage: slip [-d]

   -d enables debugging (voluminous) output.

- - - - -

slipwait.exe	Utility to wait until SLIP is up and running

   Usage: slipwait [##]

   ## specifies # of seconds to wait (default = 30)

- - - - -

slipterm.exe	Simple terminal program for making SLIP connections

   Usage: slipterm [-w[##]] [-d]

   -w says to wait for SLIP.  ##=seconds and defaults to 30.
   -d is debugging mode - continue without SLIP

- - - - -

sliphold.exe	Utility to hold a COM port open

   Usage: sliphold

- - - - -

sldetach.exe	Utility for force a detach of interface sl0

   Usage: sldetach interface

   interface is name of interface to detach - must be 'sl0'

- - - - -

slcfg.exe	Utility to test parsing SLIP configuration files

   Usage: slcfg config_file [-d]

   config_file is name of file to process.
   -d enables debugging mode (extra internal debugging output during parse)

   

+--------------------+
| Reporting Problems |
+--------------------+

Should anyone encounter problems - either usage problems or actual code
problems (especially those that cause crashes), I'd appreciate the following
being done, in order to best help me try to narrow down the problem.

     1.	Record whatever information you can as to the circumstances
	surrounding the crash, and any dump information.  If possible,
	please see if the problem is reproduceable.
     2. If you are using VJ compression, try disabling it (use the
        parameter "compression=off" in SLIP.CFG) and see if the problem
	can be reproduced.
     4. Run SLIP with the -d (debug) option and try to reproduce the
	failure.  Using debug mode will generate lots of debugging
	information to be output (and will slow down the driver).  The best
	thing to do is to redirect the output to a log file.
     5. If possible, try using the standard IBM SLIP driver in the
	same environment and see if the same result occurs.

After doing this, please send me as much information about the crash and the
resulting debug information as you can.  I guess the best thing to do is for
actual crash reports to come directly to me (I can summarize problem
environments to the list), while more general problems about configuration,
or getting the link to work can be sent to the list.

For crash information, please be as verbose as you can about the environment
in which you are running.  I may not need most of the information, but I
may not automatically know up front what I do need.


+---------------+
| Administrivia |
+---------------+

Just to keep this in one place - I can be reached via the following:

	David Bolen				e-mail:  db3l@ans.net
	Advanced Network & Services, Inc.	phone:   +1 914 789-5327
	100 Clearbook Road			fax:     +1 914 789-5310
	Elmsford, NY  10523


and mail to the mailing list for the beta version of my SLIP driver should
be sent to "os2-slip@ans.net".  Requests for additions to/deletions from the
list should be sent to "os2-slip-request@ans.net".
