    ==== WARNING = WARNING = WARNING = WARNING = WARNING = WARNING ====

     This is beta software.  It is not currently known to have bugs or
     incompatibilities with existing STiK apps; nevertheless, use this
     software at your own risk.

    ==== WARNING = WARNING = WARNING = WARNING = WARNING = WARNING ====

                             GlueSTiK v0.03b2
                      Scott Bigham   dsb@cs.duke.edu

INSTALLATION AND USE

Copy GLUESTIK.XDD and GSRESOLV.PRG to the directory where your MiNTnet
SOCKDEV.XDD resides (this should be the \MINT or \MULTITOS directory of
your boot drive).  Add the following line to your MINT.CNF file:

    exec c:\path\to\gsresolv.prg

If you don't already have a STiK config file, you will need to create
one.  Create a subdirectory STIK_CFG in the root directory of your boot
drive, and create in it a file called DEFAULT.CFG (if you want to put it
somewhere else or name it something else, consult the STiK docs for the
use of the STIK_DIR.DAT file).  This file should contain at least the
line:

    ALLOCMEM = 100000

Other STiK applications may require that additional application-specific
variables be set; consult your applications' documentation for further
information.  There are a few additional STIK variables used by GlueSTiK;
see the NEW FEATURES section below for further information.

Reboot your computer.  You should see two new programs installing
themselves:  the GluesSTiK device driver and GSRESOLV.  Now connect to your
ISP in the usual way and run your STiK apps.

COMPATIBILITY

I have done preliminary testing with the following STiK apps and found
no compatibility problems:

   - CAB v1.31
   - FINGER v1.00
   - FORECAST v0.4
   - TELNET v1.00

NEW FEATURES

* Trace Logging

GlueSTiK's debugging facilities are now a bit more useful.  Admittedly,
they will probably only be of interest to those developing STiK apps
and/or attempting to trace compatibility problems between GlueSTiK and
existing STiK apps.

GlueSTiK writes its trace log in the file GLUESTIK.LOG, in the same
directory as your DEFAULT.CFG file.  If a trace log file exists at boot
time, it is renamed to GLUESTIK.OLD; this is important in the event of
errors which cause or require a system reboot.  The level of detail of
information recorded in the trace log is initially determined by the value
of STiK variable GLUESTIK_TRACE, and can be changed at runtime with the
"gsdbglvl" command.  Allowed values are:

	0	No information reported. (default)
	1	Report fatal system errors.
	2	As above; also report error returns from STiK functions, as
		well as errors returned by MiNTnet socket functions called
		within GlueSTiK.
	3	As above; also report entry and non-error returns for STiK
		functions.
	4	As above; also report internal tracing information, such as
		calls to internal helper functions.

The "gsdbglvl" command works as follows:

	gsdbglvl 4		# sets trace level to maximum
	gsdbglvl		# with no parms, reports current trace level

Also included is the program "gslog", which can be used to write messages
directly into the trace log.  The parameters are the trace level and the
text to enter; for instance:

	gslog 3 "This is a SYSCALL-level log entry..."

TECHNICAL STUFF

Unless you're interested in how GlueSTiK works, you can stop reading
now; just note the e-mail address at the bottom to report problems.

Version 0.03 of GlueSTiK comes in two pieces.  GLUESTIK.XDD is the device
driver, which creates and manages the device U:\DEV\GLUESTIK.  It also
installs the STiK cookie and containes the STiK function table used by STiK
apps.  GSRESOLV.PRG is a separate module which runs as a background process
and handles DNS name resolution (which for various obscure reasons is
unnecessarily difficult to do inside the device driver; don't ask...).

All STiK functions are implemented as Fcntl() calls on U:\DEV\GLUESTIK
(indeed, this is how GSRESOLV is able to perform certain GlueSTiK
operations from outside the device driver).  Some GlueSTiK-specific
Fcntl()'s are also provided; see, for instance, gsdbglvl.c and gslog.c for
examples of their use.

Note that the GSRESOLV daemon and the STiK app communicate with each other
by writing into each other's memory space.  If you run MiNT without memory
protection (by renaming MINT.PRG to MINTNP.PRG), this is not a problem;
otherwise, you may need to use a program-flag setting utility to set the
memory flags of your STiK apps to global.

There are some places where I was unable to reproduce STiK's exact
functionality; you can find these places by searching the source code for
the word `Incompatibility'.  Otherwise, comments are fairly sparse, mostly
notes to myself.

testit.c is a quick-n-dirty program I threw together to do basic testing
of GlueSTiK.  It probably should not be used as a guideline for STiK
application programming. ;)  You can build it with `make test'.

BUGS

None that I know of; presumably a few that I don't.  Report any problems
you may have to me at dsb@cs.duke.edu.

That's pretty much it.  Remember, it's just a beta.

						-sbigham
