UCEi (pronounced "Uzi") --- the ultimate UCE filter
---------------------------------------------------

Having finally nailed the hanging bug (either there's a separate problem
specific to Object REXX, or OREXX was lying to me in debugging sessions:  the
hangs were in fact in REXX code which scanned for comments), the latest
version of my UCE (unsolicited commercial e-mail) filter is ready for release.

There are a *lot* of changes, even ignoring the name change.  Your old filter
files are worthless with this version... but this version includes dump
capability, so future releases will have a way to upgrade the databases even
if the file formats change.  (They didn't change physically in this case,
but logically.  Instructions for recovering your old private database below.)

The biggest change:  no more web update.  The site went away.  Again.  So
much for that.  I assume "Spamford & Sons" makes life as difficult as possible
for anyone presuming to help others deflect their trash.  The old web database
has been merged with the old private database instead.

A separate generic-header-match database has been added; instead of being
specific to addresses, it can be used to match strings in *any* header.


INSTALLATION
============

Unpack this file in your MR/2 ICE directory.  (Don't run ICE?  Good luck.)

Copy LIBDB.DLL to a directory in your LIBPATH, or leave it where it is and
insure that "." is in LIBPATH.  WARNING:  remove any older versions that
might be scattered about the LIBPATH.

Create a mail filter:  inbound or prefetch, REXX filter, REXX script = UCEi.cmd
Actions: (whatever you choose; should include copy to folder)
Disposition: preferably "don't show in inbox/outbox; don't run further filters"
This should be the *last* filter in your filter list, since external REXX
filters are fairly slow as Nick currently has them implemented.  (If you want
faster filtering, or want it not to steal focus when it's launched, lobby Nick
Knight for RexxStart() support.  :-)

You might want to inspect the "unloaded" versions of the databases and add
or remove entries as appropriate for your situation.  The included databases
are examples, and most people running this probably won't care about special
cases for the NA-Soccer mailing list, for example.


UPGRADING
=========

As above.  NOSPAM.* from the older version are worthless; delete them.

You can attempt to recover your private entries from NOSPAM.PDB as follows:
1. Rename UCEi.PDB to UCEi.PBK
2. Rename NOSPAM.PDB to UCEi.PDB
3. Run:  UCEi /PDUMP > nospupdt.cmd
4. Delete UCEi.PDB
5. Rename UCEi.PBK to UCEi.PDB
6. Run:  nospupdt
7. Delete nospupdt.cmd
8. (Optional) Run:  UCEi /PDUMP > UCEi.PDC


USAGE
=====

UCEi [/TEST[=n] message
     Test the specified message against the header pattern and address/
     domain databases; if /TEST, logging is to standard output and the
     result is printed instead of semaphored for MR/2 ICE; if =n is
     specified and n is greater than 1, all matches are printed along
     with the final per-header result

UCEi /HLIST
     List entries in header pattern database

UCEi /PLIST
     List entries in address/domain database

UCEi /PADD address Y|N
     Add an entry to the address/domain database

UCEi /HADD Y|N priority header pattern
     Add an entry to the header pattern database

UCEi /PDELETE address
     Remove an entry from the address/domain database

UCEi /HDELETE header [pattern]
     Remove the specified or all entries for the specified header from
     the header database

UCEi /HDUMP
     Dump the header pattern database as a REXX script to reload it

UCEi /PDUMP
     Dump the address/domain database as a REXX script to reload it

UCEi /DUMP
     Dump all databases as a REXX script to reload them

All of the above options can be abbreviated to the minimum unique string
except /HDUMP, /PDUMP, /DUMP, and /TEST.


FILES
=====

UCEi.CMD - the script itself
UCEi.PDB - the primary address database, a db-0.85 hash database
UCEi.HDB - the header pattern database, a db-0.85 btree database
LIBDB.DLL - a port of db-0.85 to OS/2

These files may be deleted if desired:

UCEi.PDC - the primary address database in /PDUMP format, for convenience
UCEi.HDC - the header pattern database in /HDUMP format, for convenience


KNOWN PROBLEMS
==============

None :-)

The current window will lose focus each time ICE starts this or any other
REXX filter under OS/2 Warp Version 4, due to a bug in Presentation Manager.
(Windows launched minimized still take the focus away from the foreground
window, even though they should not.)

It doesn't catch everything.  Somewhat ironically, it's *not* the professional
ooze-spewers that it misses:  despite everything, they're all rather dumb and
their messages are easily detected.  It's the amateurs who are most likely to
slip things past UCEi, because they're not following any rules and generally
don't know what rules to follow (or ignore!).  A future version may add
pattern support and body scanning to help foil these (or on the off chance
that the "pros" discover a functioning neuron between themselves).

It uses a single database across all accounts.  This doesn't strike me as a
problem, but it could relatively easily be changed.

Don't bother using it as a news filter; REXX filters can only be used as
inbound filters, whereas news is almost always run in "manual mode" where
only the headers are downloaded initially.  This makes UCEi useless for news,
although the beginnings of news support are in the script.


DISCLAIMER
==========

Any attempt to abuse the First Amendment of the U.S. Constitution by
a known UCE producer in order to suppress this program or its databases
will be treated as an attempt to deny the author his First Amendment rights,
*and by extension* the First Amendment rights of all Internet users.

And yes, in extreme cases, this *will* include First Amendment challenges
against any UCE producers who so threaten the author.

Additional warning:  it is quite obvious, even to lawyers paid to convince
courts otherwise, that nobody is forcing anyone to use this script or the
databases provided with it.  That (il)legal fiction won't hold water, so
don't waste my or anyone else's time with that particular lie unless you
want an additional lawsuit for libel.

I trust I have made my position clear.  Yours is already transparent.  Don't
push your luck.


CONTACT INFORMATION
===================

Brandon S. Allbery KF8NH
bsa@kf8nh.apk.net